Manual da API REST - Versão 1.0

Transcrição

1 Manual da API REST - Versão 1.0

2 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" ]

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 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

5 Criar um novo cliente Recuperar cliente existente Atualizar cliente 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. 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 MONTHLY QUARTERLY SEMIANNUALLY YEARLY Descrição Mensal Trimestral Semestral Anual

7 Criar uma nova assinatura Recuperar assinatura existente Atualizar assinatura 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. 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 PENDING RECEIVED OVERDUE Descrição Aguardando pagamento Cobrança paga Cobrança atrasada

9 Criar uma nova cobrança Recuperar cobrança existente Atualizar cobrança Remover cobrança DELETE Listar cobranças Listar cobranças de um cliente específico Exemplo de resposta (JSON) "object":"payment", "id":"pay_tvnbgqwwub9t", "customer":"cus_lbbjq2l4z0k7", "subscription":"sub_ni728ydjjgpg", "value":59.9, "netvalue":54.9, "originalvalue":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 enabledforcustomer 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 Recuperar notificação existente Atualizar notificação 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 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: