Ecommerce Próprio

Este guia é destinado a fornecedores que desejam implementar vendas não assistidas através de e-commerce próprio, utilizando o Tino como meio de pagamento. Ele aborda a integração do SDK para automação do fluxo de compra dos lojistas, bem como os processos de faturamento, captura do pedido, cobrança do lojista e pagamento ao fornecedor.

As outras etapas podem ser feitas via no-code ou integração via API. Abaixo, detalhamos como realizar essa integração completa via API.

1. Pré-requisitosCopied!

1.1 Autenticação

• Todas as requisições exigem o header:

  X-Api-Key: "sua-chave-api"

  shell Copy Copied!

• Caso a chave seja inválida, o sistema retornará HTTP 401.

• Para solicitar chaves de API, entre em contato via:

  • E-mail: integracoes@tino.com.br

  • WhatsApp: (11) 97298-6920

1.2 Ambientes

Cada ambiente possui sua própria API Key, garantindo segurança e separação entre testes e produção.

2. Fluxo de Configuração do SDKCopied!

2.1 Instalação e Configuração do SDK

Para integrar o SDK, adicione o seguinte código na página de checkout:

const head = document.getElementsByTagName('head')[0];
const js = document.createElement('script');

js.id = 'COMPRATINO-SDK';
js.src = '<https://checkoutsdk.tino.com.br/dist/umd/sdk.min.js>';
js.defer = true;
js.onload = () => {
  const sdkPayload = {
    apiKey: 'sua-chave-api',
    externalId: 'order-test',
    amountCents: 20500,
    maxDueDay: 30,
    cart: {
      address: 'R. Fidalga, 162 - Pinheiros',
      zipCode: '05432000',
      shippingCents: 1500,
      discountCents: 1000,
      items: [
        {
          name: 'Produto Teste',
          quantity: 2,
          amountCents: 10000
        }
      ]
    },
    customer: {
      documentNumber: '12543987000199',
      email: 'cliente@email.com'
    },
    openingMode: 'self',
    transitionType: 'automatic'
  };
  window.tino.preconfig(sdkPayload);
};

head.appendChild(js);

2.2 Parâmetros de Configuração

2.3 Inicialização do SDK

Para abrir o Tino no checkout, inclua este botão:

<button onclick="window.tino.open()">Pagar com Tino</button>

2.4 Eventos do SDK

O SDK dispara dois eventos via postMessage:

1. tino-checkout-success

   • Enviado na confirmação do pagamento.

   • Dados retornados:

     • externalId: identificador do pedido.

     • paymentReservationId: identificador da Reserva de Limite.

2. tino-checkout-close

   • Enviado quando a página do Tino é fechada.

Como capturar o evento de sucesso

window.addEventListener('message', function(event) {
  if (event.data.type === 'tino-checkout-success') {
    const { externalId, paymentReservationId } = event.data.payload;

    // Salve o paymentReservationId para operações futuras, como:
    // - Consultas de status
    // - Envio de notas fiscais
    // - Cancelamentos
  }
});

Fluxo Após Sucesso

1. Ao receber o evento tino-checkout-success:

   • Armazene o paymentReservationId

   • Atualize o status do pedido no seu sistema

   • Inicie o processo de geração da nota fiscal

2. Após gerar a nota fiscal:

   • Utilize o endpoint de envio de notas fiscais (POST /v2/limit-reservations/{id}/partial-bill)

   • Use o paymentReservationId armazenado como o {id} na URL

Importante

• O paymentReservationId é essencial para todas as operações futuras

• A reserva do limite tem validade - gere e envie a nota fiscal dentro do prazo estabelecido com o Tino

• O pedido só será capturado após o envio da nota fiscal

3. Gestão do Pedido AutorizadoCopied!

Após o pagamento, um pedido autorizado é gerado. Para a captura do pagamento precisa ser enviada a nota fiscal.

3.1 Consultar Pedido Autorizado

Antes de enviar uma nota fiscal, valide se um pedido foi autorizado consultando a Reserva de Limite.

Endpoint: Consultar Pedido Autorizado

GET /v1/limit-reservations/{external_id}
Header: X-Api-Key: sua-chave-api

3.2 Cancelamento do Pedido Autorizado

Se necessário, o pedido pode ser cancelado antes do envio da nota fiscal, liberando o limite reservado.

Endpoint: Cancelar Pedido Autorizado

DELETE /v2/limit-reservations/{id}
Header: X-Api-Key: sua-chave-api

4. Envio de Nota Fiscal e Captura do PedidoCopied!

Para capturar o pagamento, envie a(s) Nota(s) Fiscal(is) associada(s) ao pedido.

Endpoint: Enviar Nota Fiscal

POST /v2/limit-reservations/{id}/partial-bill
Header: X-Api-Key: sua-chave-api

Parâmetros da Requisição

Exemplo de Requisição

{
  "lastBatch": true,
  "nfes": [
    {
      "amount_cents": 1000,
      "data": "",
      "external_id": "123456",
      "notes": "Desconto de 10%"
    }
  ]
}

Regras Importantes:

• Prazo pra envio da nota: Até 15 dias após a emissão.

• Ajuste de valor: Permitido até 5% acima ou qualquer valor abaixo do pedido.

• Possibilidade de envio total ou parcial das notas fiscais.

5. Gestão de Pedidos CapturadosCopied!

Os pedidos capturados são aqueles que já possuem nota fiscal enviada e estão em processo de cobrança.

5.1 Consulta de Pedidos Capturados

Esse endpoint permite consultar os as frações de pedidos já capturadas.

Endpoint: Consultar Pedidos Capturados

GET /v2/invoices
Header: X-Api-Key: sua-chave-api

Parâmetros de Consulta

Exemplo de Resposta

{
  "invoices": [
    {
      "amount_cents": 12345,
      "description": "description",
      "external_id": "acfe8fad-db50-4f38-9db9-cc859ba18655",
      "merchant_document_number": "57580994000111",
      "original_amount_cents": 12345
    }
  ],
  "pagination": {
    "page_number": 1,
    "page_size": 10,
    "total_items": 15,
    "total_pages": 2
  }
}

5.2 Cancelamento da Fração de Pedido Capturada

Se necessário, a fração referente à uma nota fiscal de um pedido capturado pode ser cancelada, devolvendo o limite ao lojista.

Endpoint: Cancelamento da Fração de Pedido Capturada

DELETE /v1/invoices/{external_invoice_id}
Header: X-Api-Key: sua-chave-api

Parâmetros

5.3 Edição de Valor (Reembolso Parcial)

Se for necessário um ajuste de valor em uma fração de um pedido já capturada, o reembolso parcial pode ser solicitado.

Endpoint: Edição de Valor da Fração de Pedido Capturada

PATCH /v1/invoices/{external_invoice_id}
Header: X-Api-Key: sua-chave-api

Parâmetros

Exemplo de Requisição

{
  "amount_cents": 12345
}

5.4 Regras e Observações Importantes

• O identificador do pedido (external_invoice_id) deve ser único e pode ser o número da nota fiscal.

• Em caso de reembolso:

  • Se o comprador já pagou: o valor será reembolsado.

  • Se o pagamento estiver pendente: o limite será restituído.

  • Se o repasse ao fornecedor já foi realizado: o valor será descontado do próximo repasse.

• Parcelas são automaticamente ajustadas após qualquer edição ou cancelamento.

• Todas as operações são irreversíveis após processadas.

6. Suporte e Documentação AdicionalCopied!

Se precisar de ajuda com a integração, entre em contato com nosso suporte:

• E-mail: integracoes@tino.com.br

• WhatsApp: (11) 97298-6920

Links úteis

• Documentação da API Tino