API de Conciliação


Olá! Aqui está tudo o que você precisa saber sobre a Conciliação Ame.

Nesta seção, apresentaremos como funciona nossa aplicação de conciliação, a estrutura dos dados disponibilizados e exemplos que podem apoiar no processo de integração.


Introdução

A Conciliação Ame é uma API que disponibiliza as informações necessárias para que você possa consultar suas transações e realizar seu processo de conciliação.

A API de Conciliação utiliza o formato JSON e disponibiliza os dados em uma visão D-1, ou seja, mostra diariamente as informações referentes às transações que foram realizadas no dia anterior.

Os dados disponibilizados contemplam todo o fluxo de uma transação, apresentando uma visão sobre as vendas realizadas e capturadas, a liquidação destas vendas e os possíveis estornos que podem ter ocorrido. Essa visão, é apresentada através da disponibilização de 4 arquivos diários: Sales, Financial, Refund e Cashout.

Para consultar os dados, você precisa estar integrado conosco e realizar uma consulta (request), informando a data de solicitação e o arquivo específico para que nossa API retorne uma resposta (response) com o arquivo solicitado.

aqui vai uma imagem


Collection

Disponibilizamos as Collections, com todas as operações da API através destes arquivos,

Clique aqui para fazer o download.


Processo de integração

Para integração com a API de Conciliação em ambiente produtivo, você precisará realizar as três etapas seguintes.


1. Criar um conta no Portal Ame

O primeiro passo para integração é a criação de uma conta em nosso portal. Após criação da conta, será enviado um e-mail para validação e ativação. Este é um passo obrigatório para liberação do seu acesso em ambiente de homologação.

Para criar sua conta, acesse: Criar nova conta | Ame Digital - Desenvolvedores (sensedia.com)


2. Criar aplicação em homologação

Com o cadastro realizado e a conta ativada, você pode criar sua aplicação de conciliação para acesso aos dados de homologação.

A aplicação de Conciliação em homologação é criada por nossa equipe de suporte. Para isso, basta entrar no Portal de Desenvolvedores, fazer login em sua conta e acessar o menu de Suporte.

Após concluir seu acesso, você poderá abrir um ticket solicitando a criação e liberação de sua aplicação de Conciliação, não esqueça de informar qual deve ser o CNPJ vinculado.

Nossa equipe de suporte irá criar a aplicação de homologação e disponibilizar suas credenciais de acesso. As credenciais estarão disponíveis em até 24h após a solicitação no acesso de suporte em sua área logada.


3. Liberação em ambiente produtivo

Após realizar os passos anteriores e concluída sua integração, a aplicação será promovida para o ambiente de produção e serão disponibilizadas as novas credenciais, exclusivas para este ambiente.


Atenção

A criação destas credenciais será acompanhada por nosso time comercial, que irá solicitar e disponibilizar suas credenciais de ambiente de produção.


Ambientes

Atualmente, disponibilizamos dois ambientes para integração, o Sandbox, que é nosso ambiente isolado para realização de testes, e o ambiente de Produção, que reflete de fato informações sobre as transações que foram realizadas utilizando a Ame como meio de pagamento.


Sandbox

Os retornos desse ambiente são estáticos, ou seja, são fixos e padronizados. As credenciais de homologação operam de forma idêntica ao ambiente produtivo. É importante que a aplicação aponte para a URL do ambiente de homologação.


URL de Sandbox

http://api-amedigital.sensedia.com/hml/conciliacoes/v1/

Exemplo:

http://api-amedigital.sensedia.com/hml/conciliacoes/v1/vendas?data=2020-09-27

Produção

Este ambiente reflete os dados das transações que foram realizadas em produção, possibilitando seu processo de conciliação interna. As credenciais para acesso a esse ambiente são fornecidas após a conclusão do seu processo de integração com a Ame, acompanhado por nosso time comercial, responsável por apoiar as validações.


Atenção

Para as conciliadoras, as credenciais são liberadas por lojista, ou seja, é necessário realizar um request para cada lojista com as devidas credenciais.


Consultando seus arquivos

Agora que você possui as credenciais de acesso em produção, já pode realizar a consulta aos arquivos disponíveis. Para isso, basta fazer um GET em nossa API e verificar o status de sua solicitação.


Atenção

  • Esta consulta apresenta diariamente a visão de suas transações ocorridas em um dia específico. Os arquivos são sempre disponibilizados no dia seguinte e estão aptos para consulta a partir das 6h.
  • Ambiente de homologação: os registros estão disponíveis entre 01/01/2020 até 15/10/2020. Caso você efetue um GET fora deste período, irá obter um retorno 202.
  • Ambiente de produção: caso você obtenha um retorno 202, é necessário aguardar 1h para o processamento do arquivo. Em seguida, você poderá efetuar um novo GET para obter os retornos.

1. Sales

No arquivo de Sales, é possível consultar as vendas de um dia específico e que estão com o status de “capturada”.

Esta visão apresenta o campo orderUuid, que é um identificador único da transação que será referenciado nos arquivos Financial e Refund para acompanhamento do ciclo de vida da transação.

Para consultar o arquivo, basta realizar um Get ao endpoint correspondente, conforme a seguir. Nesse endpoint, será possível consultar as vendas de um dia específico.


GET /vendas?data=AAAA-MM-DD

Obs: a data informada no Get deve ser a data de referência do arquivo consultado.


Parâmetros Necessários:
Header:

client_id:

access_token:


Response:
{
  "data": { //Estrutura de dados
    "cnpjManager": "32778350000170", //CNPJ Ame Digital
    "nameManager": "AME DIGITAL BRASIL LTDA", //Razão Social Ame Digital
    "cnpjCustomer": "02314250000121", //CNPJ Vendedor
    "nameCustomer": "Empresa de teste", //Razão Social Vendedor
    "orders": [ //Estrutura do pedido     
      {
        "orderUuid": "265573ab-19b8-4570-a180-c9c5b47e8555", //ID do pedido
        "externalTransactionIdentifier": null, //ID do pedido na plataforma do vendedor
        "typeFile": "PURCHASE", //Tipo do arquivo ("PURCHASE")
        "createdAt": "2020-07-02T18:34:46-03:00", //Data de criação do pedido
        "totalAmountInCents": 16998, //Valor total do pedido
        "transactions": [ //Estrutura dos meios de pagamentos/parcelas
          {
            "transactionUuid": "017009ca-1cda-4f64-a7d7-9d527de9946d", //ID da transação
            "paymentUuid": "d274b55d-1aa7-40b9-b866-43453f98829f", //ID do pagamento
            "status": "CAPTURED", //Status da transação ("CAPTURED")
            "updatedAt": "2020-07-02T18:35:02-03:00", //Data de atualização
            "paymentMethod": "CASH", //Método de pagamento ("CREDIT_CARD"/"CASH"/"CASH_BACK")
            "operationType": "CREDIT", //Tipo de operação ("CREDIT")
            "grossAmountInCents": 5904, //Valor bruto
            "takeRateunit": "PERCENT", //Unidade de taxa de MDR ("PERCENT"/"CURRENCY")
            "takeRate": 184, //Taxa de MDR
            "takeRateAmountInCents": 108, //Taxa de MDR em centavos
            "takeRateUnitGateway": "CURRENCY", //Unidade de taxa de Gateway ("PERCENT"/"CURRENCY")
            "takeRateGateway": 0, //Taxa de Gateway
            "takeRateAmountInCentsGateway": 0, //Taxa de Gateway em centavos
            "netAmountInCents": 5796, //Valor liquido
            "releaseInstallment": 1,  //Número da parcela
            "numberOfInstallments": 1, //Quantidade de parcelas
            "releaseTime": 30, //Prazo de liquidação
            "scheduledFor": "2020-08-01T18:35:02-03:00" //Data de agendamento do release
          },
          {
            "transactionUuid": "b8814a6a-c284-4f2e-b569-5e0884fe7941", //ID da transação
            "paymentUuid": "2d41a40f-d98b-44a3-b947-4014bfa943a8", //ID do pagamento
            "status": "CAPTURED", //Status da transação ("CAPTURED")
            "updatedAt": "2020-07-02T18:35:02-03:00", //Data de atualização
            "paymentMethod": "CREDIT_CARD", //Método de pagamento ("CREDIT_CARD"/"CASH"/"CASH_BACK")
            "operationType": "CREDIT", //Tipo de operação ("CREDIT")
            "grossAmountInCents": 5547, //Valor bruto
            "takeRateunit": "PERCENT", //Unidade de taxa de MDR ("PERCENT"/"CURRENCY")
            "takeRate": 219, //Taxa de MDR
            "takeRateAmountInCents": 121, //Taxa de MDR em centavos
            "takeRateUnitGateway": "CURRENCY", //Unidade de taxa de Gateway ("PERCENT"/"CURRENCY")
            "takeRateGateway": 0, //Taxa de Gateway
            "takeRateAmountInCentsGateway": 0, //Taxa de Gateway em centavos
            "netAmountInCents": 5426, //Valor liquido
            "releaseInstallment": 1,  //Número da parcela
            "numberOfInstallments": 2, //Quantidade de parcelas
            "releaseTime": 30, //Prazo de liquidação
            "scheduledFor": "2020-08-01T18:35:02-03:00" //Data de agendamento do release
          },
          {
            "transactionUuid": "7899f2dc-83bf-4f8f-af4f-771888ea1fe4", //ID da transação
            "paymentUuid": "2d41a40f-d98b-44a3-b947-4014bfa943a8", //ID do pagamento
            "status": "CAPTURED", //Status da transação ("CAPTURED")
            "updatedAt": "2020-07-02T18:35:02-03:00", //Data de atualização
            "paymentMethod": "CREDIT_CARD", //Método de pagamento ("CREDIT_CARD"/"CASH"/"CASH_BACK")
            "operationType": "CREDIT", //Tipo de operação ("CREDIT")
            "grossAmountInCents": 5547, //Valor bruto
            "takeRateunit": "PERCENT", //Unidade de taxa de MDR ("PERCENT"/"CURRENCY")
            "takeRate": 219, //Taxa de MDR
            "takeRateAmountInCents": 121, //Taxa de MDR em centavos
            "takeRateUnitGateway": "CURRENCY", //Unidade de taxa de Gateway ("PERCENT"/"CURRENCY")
            "takeRateGateway": 0, //Taxa de Gateway
            "takeRateAmountInCentsGateway": 0, //Taxa de Gateway em centavos
            "netAmountInCents": 5426, //Valor liquido
            "releaseInstallment": 2,  //Número da parcela
            "numberOfInstallments": 2, //Quantidade de parcelas
            "releaseTime": 30, //Prazo de liquidação
            "scheduledFor": "2020-08-31T18:35:02-03:00" //Data de agendamento do release
          }
        ]
      }
    ]
  },
  "pageable": { //Estrutura de paginação
    "number": 0, //Pagina atual
    "hasNext": false //Indicador de existência de próxima pagina ("true"/"false")
  },
  "success": true,
  "msg": "Processed"
}


2. Financial

No arquivo Financial, é possível consultar a sua movimentação financeira de um dia específico, apresentando uma visão das liquidações e antecipações realizadas, ou seja, uma demonstração dos valores liberados na Carteira Ame.

Esta visão faz referência a transação de venda de origem (Sales) pelo campo orderReferenceOrderUuid.

Para consultar o arquivo, basta realizar um Get ao endpoint correspondente, conforme o exemplo a seguir. Neste endpoint, é possível consultar as movimentações financeiras de um dia específico.


GET /Financeiros?data=AAAA-MM-DD

Obs: a data informada no Get deve ser a data de referência do arquivo consultado.


Parâmetros Necessários:
Header:

client_id:

access_token:


Response:
{
  "data": { //Estrutura de dados
    "cnpjManager": "32778350000170", //CNPJ Ame Digital
    "nameManager": "AME DIGITAL BRASIL LTDA", //Razão Social Ame Digital
    "cnpjCustomer": "02314250000121", //CNPJ Vendedor
    "nameCustomer": "Empresa de teste", //Razão Social Vendedor
    "orders": [ //Estrutura do pedido
      {
        "orderUuid": "3dd7da22-ead2-4b73-9c1f-0502d6df3edf", //ID do release
        "referenceOrderUuid": "89aeead9-d1f9-4ca9-801a-b614c4b2e2b2", //ID do pedido
        "externalTransactionIdentifier": "2B147262771149F7A01F477BC7F5A81E",  //ID do pedido na plataforma do vendedor
        "typeFile": "RELEASE", //Tipo do arquivo ("RELEASE"/"ANTICIPATION")
        "createdAt": "2020-05-31T19:51:22-03:00", //Data de criação do pedido
        "totalAmountInCents": 16099, //Valor total do pedido
        "transactions": [ //Estrutura dos meios de pagamentos/parcelas
          {
            "transactionUuid": "637850c1-4f72-4874-b664-3813ca6121f0", //ID da parcela
            "paymentUuid": "baef4919-83f5-4ee1-9104-35f2361701ae", //ID do pagamento
            "status": "RELEASED", //Status da transação ("RELEASED")
            "updatedAt": "2020-06-30T19:51:32-03:00", //Data de atualização
            "paymentMethod": "CASH", //Método de pagamento ("CREDIT_CARD"/"CASH")
            "operationType": "CREDIT", //Tipo de operação ("CREDIT")
            "grossAmountInCents": 1040, //Valor bruto
            "takeRateunit": "PERCENT", //Unidade de taxa de MDR ("PERCENT"/"CURRENCY")
            "takeRate": 184, //Taxa de MDR
            "takeRateAmountInCents": 19, //Taxa de MDR em centavos
            "takeRateUnitGateway": "CURRENCY", //Unidade de taxa de Gateway ("PERCENT"/"CURRENCY")
            "takeRateGateway": 0, //Taxa de Gateway
            "takeRateAmountInCentsGateway": 0, //Taxa de Gateway em centavos 
            "netAmountInCents": 1021, //Valor liquido após MDR e Gateway
            "takeRateUnitAnticipation": null, //Unidade de taxa de antecipação ("PERCENT"/"CURRENCY")
            "takeRateAnticipation": null, //Taxa de antecipação
            "takeRateAnticipationAmountInCents": null, //Taxa de antecipação em centavos
            "netAnticipationAmountInCents": null, //Valor liquido após a antecipação
            "releaseInstallment": 1, //Número da parcela
            "numberOfInstallments": 1, //Quantidade de parcelas
            "releaseTime": 30, //Prazo de liquidação
            "scheduledFor": "2020-06-30T19:51:32-03:00" //Data de agendamento do release
            "releasedAt": "2020-06-30T19:51:32-03:00" //Data real em que ocorreu o release
          },
          {
            "transactionUuid": "aa53412d-3690-4aaa-bbe6-70a8ff7dd4cc",
            "paymentUuid": "ad0c846b-78c3-4c0f-8967-ac58f2687915",
            "status": "RELEASED",
            "updatedAt": "2020-06-30T19:51:32-03:00",
            "paymentMethod": "CREDIT_CARD",
            "operationType": "CREDIT",
            "grossAmountInCents": 15059,
            "takeRateunit": "PERCENT",
            "takeRate": 184,
            "takeRateAmountInCents": 277,
            "takeRateUnitGateway": "CURRENCY",
            "takeRateGateway": 0,
            "takeRateAmountInCentsGateway": 0,
            "netAmountInCents": 14782,
            "takeRateUnitAnticipation": null,
            "takeRateAnticipation": null,
            "takeRateAnticipationAmountInCents": null,
            "netAnticipationAmountInCents": null,
            "releaseInstallment": 1,
            "numberOfInstallments": 1,
            "releaseTime": 30,
            "scheduledFor": "2020-06-30T19:51:32-03:00"
            "releasedAt": "2020-06-30T19:51:32-03:00" //Data real em que ocorreu o release
          }
        ]
      }
    ]
  },
  "pageable": { //Estrutura de paginação
    "number": 0, //Pagina atual
    "hasNext": false //Indicador de existência de próxima pagina ("true"/"false")
  },
  "success": true,
  "msg": "Processed"
}


3. Refund

No arquivo Refund, é possível consultar os estornos ocorridos em um dia específico, podendo ser parcial ou integral.

Essa visão faz referência a transação de venda de origem (Sales) pelo campo orderReferenceOrderUuid.

Para consultar o arquivo, basta realizar um Get ao endpoint correspondente, conforme o exemplo a seguir. Nesse endpoint, será possível consultar os estornos de um dia específico.


GET /estornos?data=AAAA-MM-DD

Obs: a data informada no Get deve ser a data de referência do arquivo consultado.


Parâmetros Necessários:
Header:

client_id:

access_token:

Response:
{
  "data": { //Estrutura de dados
    "cnpjManager": "32778350000170", //CNPJ Ame Digital
    "nameManager": "AME DIGITAL BRASIL LTDA", //Razão Social Ame Digital
    "cnpjCustomer": "02314250000121", //CNPJ Vendedor
    "nameCustomer": "Empresa de teste", //Razão Social Vendedor
    "orders": [ //Estrutura do pedido
      {
        "orderUuid": "e720c80b-cf46-4782-ad9b-2979add13221", //ID do estorno
        "referenceOrderUuid": "8d4caca7-d265-4a3c-b5b5-b521ad8c10de", //ID do pedido
        "externalTransactionIdentifier": null, //ID do pedido na plataforma do vendedor
        "typeFile": "REFUND", //Tipo do arquivo ("REFUND")
        "createdAt": "2020-06-14T14:36:03-03:00", //Data de criação do pedido
        "totalAmountInCents": 2997, //Valor total do pedido
        "transactions": [  //Estrutura dos meios de pagamentos/parcelas
          {
            "transactionUuid": "0e5a77ec-0ac8-482e-943c-42de7d479e73", //ID da transação de estorno
            "paymentUuid": "a5770485-a2cf-41eb-aa5c-ae3b1383aef6", //ID do pagamento
            "status": "REFUNDED", //Status da transação ("REFUNDED")
            "updatedAt": "2020-06-14T14:36:04-03:00", //Data de atualização
            "paymentMethod": "CASH", //Método de pagamento ("CREDIT_CARD"/"CASH")
            "operationType": "DEBIT", //Tipo de operação ("DEBIT")
            "netAmountInCents": 1717 //Valor do estornado do vendedor
          },
          {
            "transactionUuid": "5b641993-9377-4600-b0a9-71d664e9c085", //ID da transação de estorno
            "paymentUuid": "8c34a868-8964-466b-b2f5-f7a78206fdca", //ID do pagamento
            "status": "REFUNDED", //Status da transação ("REFUNDED")
            "updatedAt": "2020-06-14T14:36:04-03:00", //Data de atualização
            "paymentMethod": "CREDIT_CARD", //Método de pagamento ("CREDIT_CARD"/"CASH")
            "operationType": "DEBIT", //Tipo de operação ("DEBIT")
            "netAmountInCents": 1255 //Valor do estornado do vendedor
          }
        ]
      }
    ]
  },
  "pageable": { //Estrutura de paginação
    "number": 0, //Pagina atual
    "hasNext": false //Indicador de existência de próxima pagina ("true"/"false")
  },
  "success": true,
  "msg": "Processed"
}


4. Cashout

No arquivo cashout, é possível consultar as retiradas da sua Carteira Ame em um dia específico.

Essa visão não faz referência a transação de venda de origem, uma vez que é uma movimentação independente realizada em sua carteira digital.

Para consultar o arquivo, basta realizar um Get ao endpoint correspondente, conforme o exemplo a seguir. Neste endpoint, será possível consultar as retiradas de um dia específico.


GET /retiradas?data=AAAA-MM-DD

Obs: a data informada no Get deve ser a data de referência do arquivo consultado.


Parâmetros Necessários:
Header:

client_id:

access_token:


Response:
{
  "data": { //Estrutura de dados
    "cnpjManager": "32778350000170", //CNPJ Ame Digital
    "nameManager": "AME DIGITAL BRASIL LTDA", //Razão Social Ame Digital
    "cnpjCustomer": "02314250000121", //CNPJ Vendedor
    "nameCustomer": "Empresa de teste", //Razão Social Vendedor
    "orders": [ //Estrutura do pedido
      {
        "orderUuid": "001d25a2-1a58-4a31-a2a8-32a77785c993", //ID da retirada
        "typeFile": "CASH_OUT", //Tipo do arquivo ("CASH_OUT")
        "createdAt": "2020-07-07T12:25:45-03:00", //Data de criação do retirada
        "totalAmountInCents": 63476, //Valor total da retirada
        "transactions": [ //Estrutura dos meios de pagamentos/parcelas
          {
            "transactionUuid": "df2090e4-99a7-45e0-984b-e58550dc1b2b", //ID da transação de retirada
            "status": "CAPTURED", //Status da transação ("CAPTURED")
            "updatedAt": "2020-07-08T14:36:04-03:00", //Data de atualização do pagamento/parcela
            "paymentMethod": "BANK_TRANSFER", //Método de pagamento ("BANK_TRANSFER")
            "operationType": "DEBIT", //Tipo de operação ("DEBIT")
            "grossAmountInCents": 63476, // Valor bruto
            "takeRateunit": "CURRENCY", //Unidade de taxa de retirada ("PERCENT"/"CURRENCY")
            "takeRate": 0, //Taxa de retirada
            "takeRateAmountInCents": 0, //Taxa de retirada em centavos
            "netAmountInCents": 63476, //Valor liquido
            "bank": "1", //Banco de destino
            "agency": "3399", //Agencia de destino
            "accountNumber": "56316" //Conta de destino
          }
        ]
      }
    ]
  },
  "pageable": { //Estrutura de paginação
    "number": 0, //Pagina atual
    "hasNext": false //Indicador de existência de próxima pagina ("true"/"false")
  },
  "success": true,
  "msg": "Processed"
}


Regra de priorização de estorno

Nossos estornos seguem a prioridade abaixo:

  1. CASHBACK
  2. CASH
  3. CREDIT_CARD
Exemplo:

Venda no valor de R$ 1.000,00 nas seguintes formas de pagamento:

R$ 200,00 em CASH

R$ 800,00 em CREDIT_CARD

Cenário 1 - Estorno de R$ 150,00

Será feito um estorno de R$ 150,00 em CASH

Cenário 2 - Estorno de R$ 300,00

Será feito um estorno de R$ 200,00 em CASH e R$ 100,00 em CREDIT_CARD

Cenário 3 - Estorno de R$ 1000,00

Será feito um estorno de R$ 200,00 em CASH e R$ 800,00 em CREDIT_CARD

Regra de estorno para parcelas não liquidadas

Em caso estorno de vendas não liquidadas fazemos a aceleração de parcelas futuras, ou seja, antecipamos as parcelas futuras sem cobrar taxa de antecipação.

Exemplo:

Venda no dia 01/01/2020 no valor de R$ 300,00 com MDR de 3% em 3 parcelas:

Agenda futura

Parcela 1 agendada para 31/01/2020 no valor de R$ 97,00

Parcela 2 agendada para 01/03/2020 no valor de R$ 97,00

Parcela 3 agendada para 31/03/2020 no valor de R$ 97,00

Cenário 1 - Estorno de R$ 300,00 no dia 15/01/2020

Parcela 1 agendamento atualizado para 15/01/2020 no valor de R$ 97,00

Parcela 2 agendamento atualizado para 15/01/2020 no valor de R$ 97,00

Parcela 3 agendamento atualizado para 15/01/2020 no valor de R$ 97,00



Retornos possíveis

A comunicação com a nossa API é realizada através de request aos endpoints informados anteriormente, sendo que podemos ter os seguintes retornos:


HTTP Status Code Significado
200 Sucesso
202 A criação do arquivo foi disparada, é necessário aguardar a geração
400 Erro na requisição
5xx Indisponibilidade


Exemplo – visão conciliação

Como visto nos tópicos anteriores, temos hoje 4 visões que são disponibilizadas via API de Conciliação para possibilitar sua conciliação financeira.

Para facilitar o entendimento sobre estes dados, disponibilizamos abaixo um exemplo JSON de cada uma dessas visões.


1. Sales – Visão de Venda

No JSON abaixo é possível identificar uma transação de venda com sua ordem única de identificação, campo orderUuid. O orderUuid é uma identificação única que apoiará no acompanhamento das movimentações relacionadas a esta transação, fazendo um vínculo em outros arquivos de conciliação que são disponibilizados (Financial e Refund).

Como pode ser observado abaixo, essa transação de venda foi realizada no dia 13/07/2021 (createdAt), no valor total de R$ 1.499,00 (totalAmountInCents) e foi paga com cartão de crédito (paymentMethod) em 1 parcela (numberOfInstallments).

Para essa transação, tivemos a cobrança de uma taxa de MDR de 1,60% (takeRate), correspondendo a R$ 23,98 (takeRateAmountInCents) do valor total de venda, ficando um valor líquido de R$ 1.475,02 (netAmountInCents) que nosso parceiro comercial irá receber.

Outra informação importante a ser observada é que essa transação de venda possui um release programado para 30 dias (releaseTime), ou seja, um prazo de 30 dias para que os valores sejam refletidos em sua carteira digital. A data exata para que este release ocorra é 12/08/2021 (scheduledFor), conforme disponibilizado no JSON.


{
    "data": {
        "cnpjManager": "32778350000170",
        "nameManager": "AME DIGITAL BRASIL LTDA",
        "cnpjCustomer": "88622659000120",
        "nameCustomer": "Cauã e Bernardo Publicidade e Propaganda Ltda",
        "orders": [
            {
                "orderUuid": "3f7ed94d-8c1e-47c0-b8a1-5b6f2c7e791e",
                "externalTransactionIdentifier": "65ED8CAABB1C485387B8A29A67296EA3",
                "typeFile": "PURCHASE",
                "createdAt": "2021-07-13T09:27:01-03:00",
                "totalAmountInCents": 149900,
                "transactions": [
                    {
                        "transactionUuid": "11933b2c-7df2-4337-8515-addcdafd9080",
                        "paymentUuid": "7cfa27b0-09ba-43b3-be8b-5c99f508f5e1",
                        "status": "CAPTURED",
                        "updatedAt": "2021-07-13T09:27:08-03:00",
                        "paymentMethod": "CREDIT_CARD",
                        "operationType": "CREDIT",
                        "grossAmountInCents": 149900,
                        "takeRateunit": "PERCENT",
                        "takeRate": 160,
                        "takeRateAmountInCents": 2398,
                        "takeRateUnitGateway": "CURRENCY",
                        "takeRateGateway": 0,
                        "takeRateAmountInCentsGateway": 0,
                        "netAmountInCents": 147502,
                        "releaseInstallment": 1,
                        "numberOfInstallments": 1,
                        "releaseTime": 30,
                        "scheduledFor": "2021-08-12T09:27:09-03:00"
                    }
                ]
            }
        ]
    },
    "pageable": {
        "number": 0,
        "hasNext": false
    },
    "success": true,
    "msg": "Processed"
}



2. Financial - Visão de Liquidação

No JSON abaixo temos a visão da liquidação dos valores que foram consultados anteriormente no arquivo de venda. Esta visão apresenta a confirmação sobre o release que estava programado para a venda e a disponibilização dos valores em sua Carteira Digital Ame.

Para identificação da transação de venda no arquivo Financial podemos utilizar o campo referenceOrderUuid. Este campo do Financial faz referência ao campo orderUuid do arquivo Sales, sendo uma identificação única da transação entre eles.


{
    "data": {
        "cnpjManager": "32778350000170",
        "nameManager": "AME DIGITAL BRASIL LTDA",
        "cnpjCustomer": "88622659000120",
        "nameCustomer": "Cauã e Bernardo Publicidade e Propaganda Ltda",
        "orders": [
            {
                "orderUuid": "0a390cb4-2640-462f-8a5c-282857e8f5ee",
                "referenceOrderUuid": "3f7ed94d-8c1e-47c0-b8a1-5b6f2c7e791e",
                "externalTransactionIdentifier": "65ED8CAABB1C485387B8A29A67296EA3",
                "typeFile": "RELEASE",
                "createdAt": "2021-07-13T09:27:01-03:00",
                "totalAmountInCents": 149900,
                "transactions": [
                    {
                        "transactionUuid": "11933b2c-7df2-4337-8515-addcdafd9080",
                        "paymentUuid": "7cfa27b0-09ba-43b3-be8b-5c99f508f5e1",
                        "status": "RELEASED",
                        "updatedAt": "2021-08-12T02:30:01-03:00",
                        "paymentMethod": "CREDIT_CARD",
                        "operationType": "CREDIT",
                        "grossAmountInCents": 149900,
                        "takeRateunit": "PERCENT",
                        "takeRate": 160,
                        "takeRateAmountInCents": 2398,
                        "takeRateUnitGateway": "CURRENCY",
                        "takeRateGateway": 0,
                        "takeRateAmountInCentsGateway": 0,
                        "netAmountInCents": 147502,
                        "takeRateUnitAnticipation": null,
                        "takeRateAnticipation": null,
                        "takeRateAnticipationAmountInCents": null,
                        "netAnticipationAmountInCents": null,
                        "releaseInstallment": 1,
                        "numberOfInstallments": 1,
                        "releaseTime": 30,
                        "scheduledFor": "2021-08-12T09:27:09-03:00",
                        "releasedAt": "2021-08-12T02:30:01-03:00"
                    }
                ]
            }
        ]
    },
    "pageable": {
        "number": 0,
        "hasNext": false
    },
    "success": true,
    "msg": "Processed"
}



3. Refund - Transação de Estorno

Caso a transação de venda tenha tido um estorno, a identificação deste estorno será realizada através do arquivo Refund, dentro do modelo JSON apresentado abaixo.

Da mesma forma que vimos no arquivo Financial, o arquivo de Refund também possui um campo chamado referenceOrderUuid. Este campo faz referência ao campo orderUuid do arquivo Sales, sendo uma identificação única da transação entre eles.

Pelo JSON abaixo, podemos observar que a transação de venda teve um estorno no valor de R$ 1.475,02 (netAmountInCents), no dia 24/08/2021 (createdAt).


{
    "data": {
        "cnpjManager": "32778350000170",
        "nameManager": "AME DIGITAL BRASIL LTDA",
        "cnpjCustomer": "88622659000120",
        "nameCustomer": "Cauã e Bernardo Publicidade e Propaganda Ltda",
        "orders": [
            {
                "orderUuid": "aef324b5-cf9e-430e-a6a9-24fcdccf0c38",
                "referenceOrderUuid": "3f7ed94d-8c1e-47c0-b8a1-5b6f2c7e791e",
                "externalTransactionIdentifier": null,
                "typeFile": "REFUND",
                "createdAt": "2021-08-24T16:32:54-03:00",
                "totalAmountInCents": 149900,
                "transactions": [
                    {
                        "transactionUuid": "6b86b671-8322-488b-9ed3-49033fc5f53c",
                        "paymentUuid": "c26d0151-500a-492b-96a2-0c48f669e87c",
                        "status": "REFUNDED",
                        "updatedAt": "2021-08-24T16:32:57-03:00",
                        "paymentMethod": "CREDIT_CARD",
                        "operationType": "DEBIT",
                        "netAmountInCents": 147502
                    }
                ]
            }
        ]
    },
    "pageable": {
        "number": 0,
        "hasNext": false
    },
    "success": true,
    "msg": "Processed"



4. Cashout – visão das retiradas da Wallet

O arquivo de cashout apresentará a visão das retiradas financeiras que foram realizadas de sua Carteira Digital Ame para outra conta bancária.

No arquivo Cashout não temos um campo de referência a uma ordem única de venda como nos casos anteriores. Isso ocorre porque os valores de retiradas de sua wallet são movimentações independentes, que podem ser realizadas a qualquer momento e sem relação ou limitação por uma ordem de venda específica.

Pelo JSON abaixo, podemos observar que a Carteira Digital Ame que estamos utilizando como exemplo fez uma retirada no dia 26/10/2021 (createdAt), no valor de 889.105,03 (totalAmountInCents). Este valor foi transferido para uma conta bancária informada no momento da retirada ( bank, agency e accountNumber), e sua atualização sobre a efetivação da retirada feita no dia 27/10/2021 (updatedAt).


{
    "data": {
        "cnpjManager": "32778350000170",
        "nameManager": "AME DIGITAL BRASIL LTDA",
        "cnpjCustomer": "88622659000120",
        "nameCustomer": "Cauã e Bernardo Publicidade e Propaganda Ltda",
        "orders": [
            {
                "orderUuid": "d0f1caa5-31e8-4e45-9c3b-d9097516d1c7",
                "typeFile": "CASH_OUT",
                "createdAt": "2021-10-26T07:34:01-03:00",
                "totalAmountInCents": 88910503,
                "transactions": [
                    {
                        "transactionUuid": "7032a65d-738e-4097-baef-74491ea4be7a",
                        "status": "CAPTURED",
                        "updatedAt": "2021-10-27T16:51:01-03:00",
                        "paymentMethod": "BANK_TRANSFER",
                        "operationType": "DEBIT",
                        "grossAmountInCents": 88910503,
                        "takeRateunit": null,
                        "takeRate": 0,
                        "takeRateAmountInCents": 0,
                        "netAmountInCents": 88910503,
                        "bank": "237",
                        "agency": "0099",
                        "accountNumber": "1211586-X"
                    }
                ]
            }
        ]
    },
    "pageable": {
        "number": 0,
        "hasNext": false
    },
    "success": true,
    "msg": "Processed"
}



Faq – Perguntas e Respostas


1. O que é a Conciliação Ame?

A Conciliação Ame é uma API que disponibiliza as informações necessárias para que você possa consultar suas transações e realizar seu processo de conciliação. Os dados são disponibilizados diariamente, permitindo que através da integração com nossa API, mantenha uma visão clara sobre o ciclo de vida de suas transações.


2. Qual o contato para solicitações ou reclamações?

As solicitações, dúvidas, problemas e reclamações podem ser direcionadas através da nossa plataforma de suporte na área logada aqui do nosso portal de desenvolvedores.


3. Qual é o dia e horário de atendimento do suporte?

O horário de atendimento é de segunda a sexta das 8h às 17h, exceto em feriados.


4. Qual o prazo (SLA) para o primeiro atendimento?

O prazo para o primeiro atendimento é de até 2h.


5. Quais informações disponibilizadas através da Conciliação?

Os dados disponibilizados contém todo o fluxo de uma transação, apresentando uma visão sobre as vendas realizadas e capturadas, a visão de liquidação destas vendas e os possíveis estornos que possam ter ocorrido. Esta visão é apresentada através da disponibilização de 4 arquivos diários: Sales, Financial, Refund e Cashout.


6. Qual o formato de disponibilização dos dados de Conciliação?

A API de Conciliação utiliza formato JSON e disponibiliza os dados em uma visão D-1, ou seja, disponibiliza diariamente as informações referentes às transações ocorridas no dia anterior.


7. Qual o período máximo de disponibilização de dados pela API de Conciliação?

Atualmente, a API disponibiliza todos os dados desde a sua data de cadastro na Ame.


8. Posso receber os dados em um formato diferente?

No momento, nossa API entrega os dados somente em formato JSON.


9. Quais Conciliadoras já estão homologadas pela Conciliação Ame e habilitadas em produção?

Confira abaixo a relação das Conciliadoras que já possuem integração conosco em ambiente produtivo:


  • AdaptiveSoft
  • All Data
  • Atos Capital
  • BoaVista Tecnologia
  • Concil
  • Equals
  • F360
  • Redesoft
  • SCOPE Con – NCR
  • Sitef Conciliação
  • Smart Concilia
  • Tecnuv
  • TrackCash
  • Zaal


10. Quais são as informações necessárias e o prazo (SLA) para inclusão de uma nova loja?

Após a solicitação recebida, é gerada uma chave de conciliação para o cliente e os dados devem ser liberados em até 2 dias úteis.


11. Quais dados são necessários para o acesso a API?

Apenas o access_token, que está vinculado a um CNPJ específico e o client_id da APP (aplicação).


12. Os dados serão disponibilizados em tempo real ou terá um delay? Caso tenha um tempo para disponibilização, qual será o prazo?

O tempo para disponibilização é de D-1, ou seja, as transações efetuadas na data do dia 21/07 serão liberadas no dia 22/07. Lembrando que, a data parâmetro informada na consulta será do dia 21/07.


Conceitos

Termo Definição
Seller/Parceiro comercial Indivíduo ou empresa responsável pela venda
JSON Formato de troca de dados entre sistemas.
orderUuid Número único de identificação de uma transação
OrderReferenceOrderUuid Número de identificação de uma transação que é referenciado.
Captura Etapa onde, após realizada a autorização do pagamento, temos a confirmação de sucesso através da captura da transação.
Sandbox Ambiente onde você pode testar a sua implementação sem precisar efetuar movimentações financeiras reais. Desta forma, você pode testar diversos cenários sem afetar a sua conta de produção.
GET Método utilizado via API, no qual o cliente pode buscar informações conosco.


Português, Brasil