Manual da API REST - Versão 1.0
Autenticação
A autenticação é feita através do fornecimento da sua API Key em todas as requisições. É possível obte-la através do menu configurações, aba API, de dentro da sua conta do Asaas. Sua API Key carrega muitos privilégios, portanto certifique-se de mantê-la secreta. Além disso, não é possível recuperá-la caso a perca, sendo necessário a geração de uma nova.
A API Key deve ser transmitida em todas as requisições no header “access_token”. Caso a chave seja inválida ou não informada você reberá como retorno o status HTTP 401.
Todas as requisições devem utilizar HTTPS. Requisições feitas através de HTTP falharão.
Resposta
Todas as repostas da API são objetos JSON.
Status HTTP de retorno
O Asaas utiliza respostas HTTP convencionais para indicar sucesso ou falha nas requisições. Via de regra, status 2xx indicam sucesso, status 4xx indicam falhas decorrentes de erros nas informações enviadas, e status 5xx indicam erros internos no servidor do Asaas.
● 200 OK - Tudo ocorreu conforme o esperado.
● 400 Bad Request - Algum parâmetro obrigatório não foi enviado ou é inválido.
● 401 Unauthorized - A API Key enviada é inválida.
● 404 Not Found - O objeto solicitado não existe.
● 500 Internal Server Error - Algo deu errado no servidor do Asaas.
Exemplo de reposta para status HTTP 400:
{
"errors":[
{
"code":"invalid_value",
"description":"O campo value deve ser informado"
}, {
"code":"invalid_dueDate",
"description":"O campo dueDate deve ser informado"
} ] }
Listagem/Paginação
É possível listar Clientes, Assinaturas, Cobranças e Notificações.
Para paginar os resultados da lista são utilizados dois parâmetros:
● limit: quantidade de objetos por página
● offset: posição do objeto a partir do qual a página deve ser carregada. O objeto inicial possui a posição 0.
Por exemplo, utilizando limit 10 e offset 0 será retornada a primeira página com 10 objetos. Utilizando limit 10 e offset 10 trará a segunda página, limit 10 e offset 20 a terceira página, e assim por diante.
O limit deve ser um valor numérico entre 1 e 100. Caso seja omitido será utilizado o valor padrão: 10.
Exemplo de resposta para listagem
{
"object":"list", "hasMore":true, "limit":10, "offset":0, "data":[
{
"object":"payment", "id":"pay_tVnBgQwwUb9T", "customer":170,
"value":159.0, "netValue":154.0, "originalValue":null, "nossoNumero":"30086894",
"description":"Cobrança Junho/2014", "billingType":"BOLETO",
"status":"PENDING", "dueDate":"20/06/2014", "paymentDate":"01/06/2014",
"invoiceUrl":"https://www.asaas.com/p/vc/vVOYPtI8", "boletoUrl":"https://www.asaas.com/b/pdf/vVOYPtI8", "deleted":false
}, {...}, {...}
] }
Os objetos localizados, de acordo com os parâmetros da requisição, ficam no atributo “data”. O atributo
“hasMore” terá o valor true sempre houver mais uma página a ser buscada, considerando o “offset”
previamente utilizado.
Objeto Cliente (customer)
Atributos
Nome Tipo Finalidade
id String Identificador único do cliente
name String Nome do cliente
email String Email do cliente
company String Nome da compania
phone String Telefone do cliente. Formato: (00) 0000-0000 mobilePhone String Telefone celular do cliente. Formato: (00) 0000-0000 address String Endereço da assinatura (Rua, Av, etc)
addressNumber String Número do endereço
complement String Complemento do endereço
province String Bairro do endereço
city String Cidade do cliente
state String Estado (UF) do cliente. Utilizar valores padrão (SP, RJ, SC, MG, BA, etc) country String País do cliente. Somente Brasil.
postalCode String Código postal (CEP)
cpfCnpj String CPF ou CNPJ do cliente (somente números)
personType String Define se cliente pessoa física ou juridica. Valores válidos: FISICA ou JURIDICA subscriptions Lista Lista de assinaturas do cliente, caso exista. Verificar objeto “subscription”.
payments Lista Lista de cobranças do cliente, caso exista. Verificar objeto “payment”
notifications Lista Lista de notificações do cliente, caso exista. Verificar objeto “notification”
Criar um novo cliente
POST https://asaas.com/api/v1/customers
Recuperar cliente existente
GET https://asaas.com/api/v1/customers/{CUSTOMER_ID}
Atualizar cliente
POST https://asaas.com/api/v1/customers/{CUSTOMER_ID}
Remover cliente
DELETE https://asaas.com/api/v1/customers/{CUSTOMER_ID}
Listar clientes
GET https://asaas.com/api/v1/customers
Exemplo de resposta (JSON)
{
"object":"customer", "id":"cus_LBbjQ2L4z0K7", "name":"João Silva",
"email":"[email protected]", "company":null,
"phone":"(11) 00000000",
"mobilePhone":"(11) 000000000", "address":"Rua Adalberto Silva", "addressNumer":null,
"complement":"Apto 205", "province":null,
"city":"São Paulo", "state":"SP", "country":"Brasil", "postalCode":null,
"cpfCnpj":"089.926.717-33", "personType":null,
"deleted":false, "subscriptions":{...}, "payments":{...}, "notifications":{...}
}
Objeto Assinatura (subscription)
Atributos
Nome Tipo Finalidade
id String Identificar único da assinatura
customer String Identificador único do cliente
value Double Valor da assinatura
nextDueDate Data (dd/MM/yyy) Data de vencimento da próxima cobrança
cycle String Intervalo de cobrança. Veriricar tabela de intervalos.
billingType String Forma de pagamento.. Valores válidos: BOLETO.
description String Descrição da assinatura
payments Lista Lista de cobranças da assinatura
Intervalos de assinatura
Valor Descrição
MONTHLY Mensal
QUARTERLY Trimestral SEMIANNUALLY Semestral
YEARLY Anual
Criar uma nova assinatura
POST https://asaas.com/api/v1/subscriptions
Recuperar assinatura existente
GET https://asaas.com/api/v1/subscriptions/{SUBSCRIPTION_ID}
Atualizar assinatura
POST https://asaas.com/api/v1/subscriptions/{SUBSCRIPTION_ID}
Remover assinatura
DELETE https://asaas.com/api/v1/subscriptions/{SUBSCRIPTION_ID}
Listar assinaturas
GET https://asaas.com/api/v1/subscriptions
Listar assinaturas de um cliente específico
GET https://asaas.com/api/v1/customers/{CUSTOMER_ID}/subscriptions
Exemplo de resposta (JSON)
{
"object":"subscription", "id":"sub_ni728YdjJgpG", "customer":"cus_LBbjQ2L4z0K7", "value":59.9,
"nextDueDate":"06/07/2014", "cycle":"MONTHLY",
"description":"Plano 2 vezes por semana", "billingType":"BOLETO",
"deleted":false, "payments":{
"object":"list", "hasMore":false, "limit":10, "offset":0, "data":[
{...}, {...}
] } }
Objeto Cobrança (payment)
Atributos
Nome Tipo Finalidade
id String Identificador único da cobrança
customer String Identificador único do cliente
subscription String Identificador único da assinatura, quando houver.
billingType String Forma de pagamento. Valores válidos: BOLETO.
value Double Valor da cobrança
netValue Double Valor líquido (calculado pelo Asaas)
originalValue Double Valor original (preenchido somente quando a cobrança é recebida com valor diferente do cadastrado)
dueDate Date Data de vencimento.
status String Status da cobrança (Verificar tabela de status).
nossoNumero String Identificador único do boleto bancário description String Descrição da cobrança
invoiceUrl String Link público para a fatura
boletoUrl String Link público para dow nload do PDF do boleto
Status de cobrança
Valor Descrição
PENDING Aguardando pagamento RECEIVED Cobrança paga OVERDUE Cobrança atrasada
Criar uma nova cobrança
POST https://asaas.com/api/v1/payments
Recuperar cobrança existente
GET https://asaas.com/api/v1/payments/{PAYMENT_ID}
Atualizar cobrança
POST https://asaas.com/api/v1/payments/{PAYMENT_ID}
Remover cobrança
DELETE https://asaas.com/api/v1/payments/{PAYMENT_ID}
Listar cobranças
GET https://asaas.com/api/v1/payments
Listar cobranças de um cliente específico
GET https://asaas.com/api/v1/customers/{CUSTOMER_ID}/payments
Exemplo de resposta (JSON)
{
"object":"payment", "id":"pay_tVnBgQwwUb9T", "customer":"cus_LBbjQ2L4z0K7", "subscription":"sub_ni728YdjJgpG", "value":59.9,
"netValue":54.9, "originalValue":null, "nossoNumero":"07691040", "description":null, "billingType":"BOLETO", "status":"PENDING", "dueDate":"06/06/2014", "paymentDate":null,
"invoiceUrl":"https://www.asaas.com/p/vc/vVOYPtI8",, "boletoUrl":"https://www.asaas.com/b/pdf/vVOYPtI8",, "deleted":false
}
Objeto Notificação (notification)
Atributos
Nome Tipo Finalidade
id String Identificador único da notificação
customer String Identificador único do cliente
event String Tipo de evento (Verificar tabela de eventos)
scheduleOffset Integer Somente para o evento PAYMENT_DUEDATE_WARNING.
Especifica quantos dias antes do vencimento a notificação deve ser enviada. Valores válidos: 0, 5, 10 ou 15
emailEnabledForProvider Boolean Desabilita/habilita envio de email para o fornecedor smsEnabledForProvider Boolean Desabilita/habilita envio de sms para o fornecedor emailEnabledForCustomer Boolean Desabilita/habilita envio de email para o cliente smsEnabledForCustomer Boolean Desabilita/habilita envio de sms para o cliente enabled Boolean Desabilita/habilita a notificação
Eventos disponíveis
Nome Evento
PAYMENT_CREATED Geração de nova cobrança
PAYMENT_UPDATED Alteração no vencimento ou valor de cobrança existente.
PAYMENT_RECEIVED Confirmação de pagamento.
PAYMENT_OVERDUE Cobrança vencida
PAYMENT_DUEDATE_WARNING Aviso de vencimento da cobrança
Criar uma nova notificação
POST https://asaas.com/api/v1/notifications
Recuperar notificação existente
GET https://asaas.com/api/v1/notifications/{NOTIFICATION_ID}
Atualizar notificação
POST https://asaas.com/api/v1/notifications/{NOTIFICATION_ID}
Remover notificação
DELETE https://asaas.com/api/v1/notifications/{NOTIFICATION_ID}
Listar notificações
GET https://asaas.com/api/v1/notifications
Listar notificações de um cliente específico
GET https://asaas.com/api/v1/customers/{CUSTOMER_ID}/notifications
Exemplo de resposta (JSON)
{
"object":"notification", "id":"not_okSCr4Uo4HP4", "customer":"cus_LBbjQ2L4z0K7", "enabled":true,
"emailEnabledForProvider":false, "smsEnabledForProvider":false, "emailEnabledForCustomer":true, "smsEnabledForCustomer":false, "event":"PAYMENT_DUEDATE_WARNING", "scheduleOffset":0,
"deleted":false }
