Introdução
Seja bem-vindo(a) a documentação do Fintera Recebíveis.
Autenticação
Todo acesso à API é feito utilizando o atributo fintera_api_token no header da requisição.
O Fintera api token pode ser obtido na página de Gerenciar Conta Fintera, ao entrar na aba de Integrações.
Recebíveis
Criar Recebível
Cria recebível na entidade, a qual o fintera_api_token pertence.
Endpoint
POST api/v1/receivables
curl --location --request POST 'https://recebiveis.fintera.com.br/api/v1/receivables' \
--header 'fintera_api_token: <SEU_FINTERA_API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"receivable": {
"deposit_account_id": 29,
"external_id": "5eb1c5f2-75b5-43b4-8f48-3c25338821ff",
"description": "Compra de roupas",
"observation": "Pedido feito pelo site",
"gross_value": 200.50,
"payment_method": "credit_card",
"acquirer_slug": "redecard",
"card_brand": "mastercard",
"payment_processed_at": "2023-03-16T13:59:59.000-03:00",
"installments_count": 1,
"nsu": "1234567890",
"authorization_code": "987654",
"tid": "0123456789",
"document": "202300001",
"document_date": "2023-03-16",
"customer_document": "1111111111111",
"customer_name": "Joyce da Silva",
"nfe_url": "https://www.exemplo.com/nfe/123456789"
}
}'
O exemplo acima resulta o seguinte JSON:
[{
"id": "705f17c5-5758-44e2-936b-6c3b34d6060e",
"description": "Compra de roupas",
"observation": "Pedido feito pelo site",
"gross_value": "200.5",
"payment_method": "credit_card",
"acquirer_product": null,
"payment_processed_at": "2023-03-16T13:59:59.000-03:00",
"installment_number": 1,
"installments_count": 1,
"nsu": "1234567890",
"authorization_code": "987654",
"tid": "0123456789",
"document": "202300001",
"document_date": "2023-03-16",
"expected_payment_value": null,
"paid_value": null,
"expected_service_rate": null,
"service_rate": null,
"service_rate_check_status": "pending",
"payment_check_status": "pending",
"expected_payment_date": null,
"paid_at": null,
"customer_document": "1111111111111",
"customer_name": "Joyce da Silva",
"nfe_url": "https://www.exemplo.com/nfe/123456789",
"entity_id": "bb9880e5-751c-45ed-a713-4a0a13768e7f",
"created_at": "2023-03-16T15:34:55.983-03:00",
"updated_at": "2023-03-16T15:34:55.983-03:00",
"external_id": "5eb1c5f2-75b5-43b4-8f48-3c25338821ff",
"deposit_account_id": 29,
"status": "liquidate",
"integration_id": null,
"bank_code": null,
"bank_agency": null,
"bank_account_number": null,
"acquirer_slug": "redecard",
"card_brand": "mastercard",
"receivable_reconciliation_id": null,
"payable_reconciliation_id": null,
"cancellation_reason": null,
"cancellation_adjustment_id": null,
"anticipated": false
}]
Atributos do recebível
| Atributo | Obrigatório | Descrição |
|---|---|---|
| deposit_account_id | Não | Id externo da conta caixa do Financeiro. |
| external_id | Não | Id externo do pagamento de origem do recebível (Se informado, terá sua unicidade validada). |
| description | Não | Descrição do recebível. |
| observation | Não | Observações adicionais. |
| gross_value | Sim | O valor bruto do recebível, sem descontos ou taxas. |
| payment_method | Sim | A forma de pagamento (opções aceitas: credit_card, debit_card, boleto, bank_transfer, pix, cash, bank_check, others). |
| acquirer_slug | Não | O identificador da adquirente (opções aceitas: redecard, cielo, getnet, stone, sipag) |
| card_brand | Sim (caso payment_method seja credit_card ou debit_card e o acquirer_slug tenha sido informado) | A bandeira do cartão de crédito utilizado (opções aceitas: agiplan, amex, aura, banescard, banrisul, cabal, convenio_loja, credsystem, credz, diners, elo, hipercard, jcb, maestro, mastercard, outros, redecard, redeshop, sorocred, valecard, visa, visa_electron) |
| payment_processed_at | Sim | A data e hora em que o pagamento foi processado, com fuso de Brasília. |
| installments_count | Sim | O número total de parcelas. |
| nsu | Sim (caso payment_method seja credit_card ou debit_card e o acquirer_slug tenha sido informado) | Número sequencial único da transação, utilizado para identificar a transação junto à adquirente. |
| authorization_code | Sim (caso payment_method seja credit_card ou debit_card e o acquirer_slug tenha sido informado) | O código de autorização da transação. |
| tid | Não | número de identificação da transação online. |
| document | Não | Número da Nota Fiscal. |
| document_date | Não | Data da emissão da Nota Fiscal. |
| customer_document | Não | Documento (CPF/CNPJ) do cliente. |
| customer_name | Não | O nome do cliente |
| nfe_url | Não | A URL da Nota Fiscal. |
Cancelar ou Estornar Recebível
Cancela ou estorna recebível na entidade, a qual o fintera_api_token pertence.
O estorno acontecerá caso o recebível já esteja liquidado, caso contrário, o cancelamento ocorrerá.
Endpoint
PUT api/v1/receivables/<RECEIVABLE_ID>/cancel_or_refund
curl --location --request PUT 'https://recebiveis.fintera.com.br/api/v1/receivables/705f17c5-5758-44e2-936b-6c3b34d6060e/cancel_or_refund' \
--header 'fintera_api_token: <SEU_FINTERA_API_TOKEN>' \
--header 'Content-Type: application/json' \
O exemplo acima resulta o seguinte JSON:
{
"id": "705f17c5-5758-44e2-936b-6c3b34d6060e",
"status": "cancelled",
"description": "Compra de roupas",
"observation": "Pedido feito pelo site",
"gross_value": "200.5",
"payment_method": "credit_card",
"acquirer_product": null,
"payment_processed_at": "2023-03-16T13:59:59.000-03:00",
"installment_number": 1,
"installments_count": 1,
"nsu": "1234567890",
"authorization_code": "987654",
"tid": "0123456789",
"document": "202300001",
"document_date": "2023-03-16",
"expected_payment_value": null,
"paid_value": null,
"expected_service_rate": null,
"service_rate": null,
"service_rate_check_status": "pending",
"payment_check_status": "pending",
"expected_payment_date": null,
"paid_at": null,
"customer_document": "1111111111111",
"customer_name": "Joyce da Silva",
"nfe_url": "https://www.exemplo.com/nfe/123456789",
"entity_id": "bb9880e5-751c-45ed-a713-4a0a13768e7f",
"created_at": "2023-03-16T15:34:55.983-03:00",
"updated_at": "2023-03-16T15:34:55.983-03:00",
"external_id": null,
"deposit_account_id": null,
"integration_id": null,
"bank_code": null,
"bank_agency": null,
"bank_account_number": null,
"acquirer_slug": "redecard",
"card_brand": "mastercard",
"receivable_reconciliation_id": null,
"payable_reconciliation_id": null,
"cancellation_reason": null,
"cancellation_adjustment_id": null,
"anticipated": false
}
Cancelar Recebível
Cancelar recebível na entidade, a qual o fintera_api_token pertence.
Endpoint
PUT api/v1/receivables/<RECEIVABLE_ID>/cancel
curl --location --request PUT 'https://recebiveis.fintera.com.br/api/v1/receivables/705f17c5-5758-44e2-936b-6c3b34d6060e/cancel' \
--header 'fintera_api_token: <SEU_FINTERA_API_TOKEN>' \
--header 'Content-Type: application/json' \
O exemplo acima resulta o seguinte JSON:
{
"id": "705f17c5-5758-44e2-936b-6c3b34d6060e",
"status": "cancelled",
"description": "Compra de roupas",
"observation": "Pedido feito pelo site",
"gross_value": "200.5",
"payment_method": "credit_card",
"acquirer_product": null,
"payment_processed_at": "2023-03-16T13:59:59.000-03:00",
"installment_number": 1,
"installments_count": 1,
"nsu": "1234567890",
"authorization_code": "987654",
"tid": "0123456789",
"document": "202300001",
"document_date": "2023-03-16",
"expected_payment_value": null,
"paid_value": null,
"expected_service_rate": null,
"service_rate": null,
"service_rate_check_status": "pending",
"payment_check_status": "pending",
"expected_payment_date": null,
"paid_at": null,
"customer_document": "1111111111111",
"customer_name": "Joyce da Silva",
"nfe_url": "https://www.exemplo.com/nfe/123456789",
"entity_id": "bb9880e5-751c-45ed-a713-4a0a13768e7f",
"created_at": "2023-03-16T15:34:55.983-03:00",
"updated_at": "2023-03-16T15:34:55.983-03:00",
"external_id": null,
"deposit_account_id": null,
"integration_id": null,
"bank_code": null,
"bank_agency": null,
"bank_account_number": null,
"acquirer_slug": "redecard",
"card_brand": "mastercard",
"receivable_reconciliation_id": null,
"payable_reconciliation_id": null,
"cancellation_reason": null,
"cancellation_adjustment_id": null,
"anticipated": false
}
Estornar Recebível
Estornar recebível na entidade, a qual o fintera_api_token pertence.
Pré-requisitos
É necessário que o recebível esteja liquidado para que se possa solicitar estorno.
Endpoint
PUT api/v1/receivables/<RECEIVABLE_ID>/refund
curl --location --request PUT 'https://recebiveis.fintera.com.br/api/v1/receivables/705f17c5-5758-44e2-936b-6c3b34d6060e/refund' \
--header 'fintera_api_token: <SEU_FINTERA_API_TOKEN>' \
--header 'Content-Type: application/json' \
O exemplo acima resulta o seguinte JSON:
{
"id": "705f17c5-5758-44e2-936b-6c3b34d6060e",
"status": "refunded",
"description": "Compra de roupas",
"observation": "Pedido feito pelo site",
"gross_value": "200.5",
"payment_method": "credit_card",
"acquirer_product": null,
"payment_processed_at": "2023-03-16T13:59:59.000-03:00",
"installment_number": 1,
"installments_count": 1,
"nsu": "1234567890",
"authorization_code": "987654",
"tid": "0123456789",
"document": "202300001",
"document_date": "2023-03-16",
"expected_payment_value": null,
"paid_value": "200.5",
"expected_service_rate": null,
"service_rate": null,
"service_rate_check_status": "pending",
"payment_check_status": "pending",
"expected_payment_date": null,
"paid_at": "2023-03-18",
"customer_document": "1111111111111",
"customer_name": "Joyce da Silva",
"nfe_url": "https://www.exemplo.com/nfe/123456789",
"entity_id": "bb9880e5-751c-45ed-a713-4a0a13768e7f",
"created_at": "2023-03-16T15:34:55.983-03:00",
"updated_at": "2023-03-16T15:34:55.983-03:00",
"external_id": null,
"deposit_account_id": null,
"integration_id": null,
"bank_code": null,
"bank_agency": null,
"bank_account_number": null,
"acquirer_slug": "redecard",
"card_brand": "mastercard",
"receivable_reconciliation_id": null,
"payable_reconciliation_id": null,
"cancellation_reason": null,
"cancellation_adjustment_id": null,
"anticipated": false
}
Status possíveis de estorno
| Atributo | Valor | Descrição |
|---|---|---|
| status | refunded | Estornado |
| status | refunde | A estornar |
Status inicial ao se solicitar um estorno
| Atributo | Valor | Resposta |
|---|---|---|
| payment_method | credit_card | refunded |
| payment_method | debit_card | refunded |
| payment_method | bank_transfer | refunde |
| payment_method | boleto | refunde |
| payment_method | cash | refunde |
| payment_method | pix | refunde |
| payment_method | bank_check | refunde |
| payment_method | others | refunde |