Manual de Integração - Versão 1.0. Esta é uma versão antiga da API, se for iniciar uma nova integração utilize a v3:

Transcrição

1 Manual de Integração - Versão 1.0 Esta é uma versão antiga da API, se for iniciar uma nova integração utilize a v3:

2 Autenticação A autenticação é feita através do fornecimento da sua API Key em todas as requisições. É possível obtê-la através do menu configurações, aba Integração, 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ê receberá 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" ]

3 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":" ", "description":"cobrança Junho/2014", "billingtype":"boleto", "status":"pending", "duedate":"20/06/2014", "paymentdate":"01/06/2014", "invoiceurl":" ", "boletourl":" ", "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.

4 Objeto Cliente (customer) Atributos Nome Tipo Finalidade id String Identificador único do cliente name String Nome do cliente String do cliente company String Nome da compania phone String Telefone do cliente. Formato: (00) mobilephone String Telefone celular do cliente. Formato: (00) 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 Identificador único da cidade 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 Filtros de listagem Atributo Tipo Descrição name String Filtra os clientes por nome ou hasoverduepayments Boolean Filtra os clientes com cobranças vencidas. Valores: true para clientes com cobranças vencidas; false para clientes sem cobranças vencidas

5 Criar um novo cliente POST Recuperar cliente existente Atualizar cliente POST Remover cliente DELETE Listar clientes Exemplo de resposta (JSON) "object":"customer", "id":"cus_lbbjq2l4z0k7", "name":"joão Silva", "company":null, "phone":"(11) ", "mobilephone":"(11) ", "address":"rua Adalberto Silva", "addressnumer":null, "complement":"apto 205", "province":null, "city":"são Paulo", "state":"sp", "country":"brasil", "postalcode":null, "cpfcnpj":" ", "persontype":null, "deleted":false, "subscriptions":..., "payments":..., "notifications":...

6 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. Verificar 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 MONTHLY QUARTERLY SEMIANNUALLY YEARLY Descrição Mensal Trimestral Semestral Anual Filtros de listagem Atributo Tipo Descrição description String Filtra as assinaturas por descrição, nome do cliente ou do cliente customer String Filtra as assinatura pelo identificar único do cliente cycle String Filtra as assinaturas pelo tipo de intervalo

7 Criar uma nova assinatura POST Recuperar assinatura existente Atualizar assinatura POST Remover assinatura DELETE Listar assinaturas Listar assinaturas de um cliente específico 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":[...,... ]

8 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, TRANSFER, DEPOSIT. Na criação, são aceitos somente 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) interestvalue Double Valor de multa e juros, quando houver. 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 download do PDF do boleto Status de cobrança Valor PENDING RECEIVED OVERDUE Descrição Aguardando pagamento Cobrança paga Cobrança atrasada Filtros de listagem Atributo Tipo Descrição description String Filtra as cobranças por descrição, nome do cliente ou do cliente customer String Filtra as cobranças pelo identificar único do cliente subscription String Filtra as cobranças pelo identificar único da assinatura status String Filtra as cobranças por status (Verificar tabela de status)

9 Criar uma nova cobrança POST Recuperar cobrança existente Atualizar cobrança POST Remover cobrança DELETE Listar cobranças Listar cobranças de um cliente específico Listar cobranças de uma assinatura específica h ttps:// Exemplo de resposta (JSON) "object":"payment", "id":"pay_tvnbgqwwub9t", "customer":"cus_lbbjq2l4z0k7", "subscription":"sub_ni728ydjjgpg", "value":59.9, "netvalue":54.9, "originalvalue":null, "interestvalue":null, "nossonumero":" ", "description":null, "billingtype":"boleto", "status":"pending", "duedate":"06/06/2014", "paymentdate":null, "invoiceurl":" ",, "boletourl":" ",, "deleted":false

10 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 enabledforprovider Boolean Desabilita/habilita envio de para o fornecedor smsenabledforprovider Boolean Desabilita/habilita envio de sms para o fornecedor enabledforcustome r Boolean Desabilita/habilita envio de para o cliente smsenabledforcustomer Boolean Desabilita/habilita envio de sms para o cliente enabled Boolean Desabilita/habilita a notificação Eventos disponíveis Nome PAYMENT_CREATED PAYMENT_UPDATED PAYMENT_RECEIVED PAYMENT_OVERDUE PAYMENT_DUEDATE_WARNING Evento Geração de nova cobrança Alteração no vencimento ou valor de cobrança existente. Confirmação de pagamento. Cobrança vencida Aviso de vencimento da cobrança

11 Criar uma nova notificação POST Recuperar notificação existente Atualizar notificação POST Remover notificação DELETE Listar notificações Listar notificações de um cliente específico Exemplo de resposta (JSON) "object":"notification", "id":"not_okscr4uo4hp4", "customer":"cus_lbbjq2l4z0k7", "enabled":true, " enabledforprovider":false, "smsenabledforprovider":false, " enabledforcustomer":true, "smsenabledforcustomer":false, "event":"payment_duedate_warning", "scheduleoffset":0, "deleted":false

12 Objeto Cidade (city) O objeto Cidade deve ser utilizado somente para consulta, não sendo possível alterar ou criar novos registros. Para listagem, o seguintes campos estão disponíveis para filtro: ibgecode e name. Atributos Nome Tipo Finalidade id String Identificador único da cidade ibgecode String Código do IBGE da cidade name String Nome do município districtcode String Código do distrito district String Nome do distrito state String Sigla do estado da cidade Recuperar cidade existente Listar cidades Exemplo de resposta (JSON) "object":"city", "id": "6198", "ibgecode:" ", "name:"são Paulo", "districtcode: "00", "district":"são Paulo", "state":"sp

13 POST de notificação Opcionalmente, você pode configurar o Asaas para que seja enviado um POST para o sua aplicação sempre que ocorrerem alterações em uma cobrança. Os eventos que geram notificações deste tipo são: criação, confirmação de pagamento, vencimento, exclusão e alteração de dados da cobrança. Para habilitar estas notificações, acesse a área de Configurações do Asaas, Aba Integração, e informe a URL da sua aplicação que deve receber o POST. Para que o Asaas considere o POST como enviado, o status HTTP da resposta deve ser 200, além de conter o texto SUCCESS. A sincronização é feita a cada um minuto, e caso as respostas da sua aplicação não respeitem estas regras por 30 tentativas consecutivas, a fila de sincronização é interrompida. Os eventos continuam sendo gerados pelo Asaas, porém não são enviados para a sua aplicação. Uma vez que a sincronização seja reiniciada, todos os eventos pendentes serão processados. O dado enviado é a representação de um objeto JSON, contendo o evento e todos os dados atualizados da cobrança que o originou. Esta informação estará disponível no atributo data da requisição. Verifique a tabela de eventos para saber o que cada um deles representa. Segue exemplo do objeto enviado: "event": "PAYMENT_RECEIVED", "payment": "object": "payment", "id": "pay_neuasoot62s2", "customer": "cus_8gy4cpn3vxrm", "subscription": "sub_9tc4zby0gwjl", "value": 10.15, "netvalue": 5.15, "originalvalue": null, "nossonumero": " ", "description": "Plano Mensal", "billingtype": "BOLETO", "status": "RECEIVED", "duedate": "06/07/2014", "paymentdate": null, "invoiceurl": " "boletourl": " "deleted": false

14 Eventos disponíveis Nome PAYMENT_CREATED PAYMENT_UPDATED PAYMENT_RECEIVED PAYMENT_OVERDUE PAYMENT_DELETED Evento Geração de nova cobrança Alteração no vencimento ou valor de cobrança existente. Confirmação de pagamento. Cobrança vencida Cobrança removida

15 Aplicativo para testes Para testar a API sugerimos que seja utilizado o aplicativo REST Console, disponível na Chrome Web Store. Com ele é possível testar todos os métodos da API, incluindo recuperação, criação e atualização de dados. Acesse: