# API Gubo

> API REST da Gubo (produção sob demanda de vestuário com a marca do cliente). Lê o catálogo da marca, vincula os SKUs da loja às variantes, cota o frete (transportadora exata, mais barata ou mais rápida), cria pedidos (por SKU da variante ou por produto + cor + tamanho), paga com o saldo da carteira, cancela antes do pagamento e acompanha até a entrega por webhooks assinados ou consulta incremental. Base: https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/v1. Autenticação: `Authorization: Bearer gubo_test_…|gubo_live_…` (a chave decide o modo). Documentação em português.

Regras que não podem ser quebradas:
- Criar, pagar e cancelar pedidos exigem `Idempotency-Key`; reuse a mesma chave em todas as repetições da mesma operação. Cotação de frete não usa; em `PUT /vinculos` é opcional.
- Frete: em `entrega` use `servico` (código de `GET /fretes/servicos`) ou `preferencia` (`mais_barata` | `mais_rapida`), nunca os dois; `se_indisponivel` só com `servico`.
- Vínculos: `PUT /vinculos` aceita até 100 itens e devolve um resultado por item; vínculo errado faz o pedido sair com a peça errada, então na dúvida não vincule.
- `referencia` é o id do pedido no sistema do cliente, única por modo; `409 referencia_duplicada` traz `erro.detalhes.pedido_id` e deve ser tratado como sucesso.
- Dinheiro é inteiro em centavos; os campos terminam em `_centavos`.
- Repita só em 429, 5xx, falha de rede e `409 idempotencia_em_andamento`, respeitando `Retry-After`.
- Campo desconhecido no corpo gera `422 campo_desconhecido`; ignore campos desconhecidos na resposta; `situacao` desconhecida = em andamento.
- Webhooks: HMAC-SHA256 sobre `"<t>.<corpo bruto>"`, cabeçalho `Gubo-Assinatura: t=…,v1=…`, tolerância de 5 min, deduplique por `id`, ordene por `pedido.versao`.
- Não existe `POST /pedidos`; use `/pedidos/por-variante` ou `/pedidos/por-produto`.

## Começar

- [Visão geral](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/visao-geral.md): O que a API faz, o fluxo de um pedido e as regras de ouro
- [Início rápido](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/inicio-rapido.md): primeiro pedido de teste, pago e entregue, em 10 minutos
- [Autenticação](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/autenticacao.md): chaves, modos teste e produção, escopos, IPs, rotação e bloqueio por falhas

## Guias

- [Criar pedidos](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/criar-pedido.md): criar pedidos por SKU da variante ou por produto, cor e tamanho, com entrega e frete
- [Fretes](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/fretes.md): cotação com preço final, transportadora exata, mais barata ou mais rápida, prazos e limites
- [Vínculos de SKU](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/vinculos.md): ligar o SKU da loja à variante da Gubo, em lotes, com roteiro para agentes de IA
- [Pagar](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/pagar.md): pagamento automático ou manual com o saldo, valor esperado e saldo insuficiente
- [Acompanhar pedidos](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/acompanhar.md): ciclo de vida, situações, pendências, consulta incremental e versão do pedido
- [Webhooks](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/webhooks.md): eventos, formato, novas tentativas e verificação da assinatura
- [Modo teste](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/modo-teste.md): frete simulado, carteira fictícia, vínculos de teste, avanço manual e CEPs de cenário
- [Ir para produção](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/producao.md): checklist e ativação da produção pela dona da loja

## Referência

- [Referência da API](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/referencia.md): todas as rotas, com escopo e link para o detalhe
- [Convenções](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/convencoes.md): identificadores, dinheiro, datas, paginação, cabeçalhos, idempotência, limites e versões
- [Erros](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/erros.md): todos os códigos de erro, o que fazer e se vale repetir
- [Conexão](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/conexao.md): loja, modo, escopos, limites e consumo da chave
- [Catálogo e domínios](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/catalogo.md): produtos, variantes (SKU padrão e vinculado), cores e tamanhos válidos para criar pedidos
- [Pedidos](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/pedidos.md): objeto Pedido e rotas de consulta, lista, pagamento e cancelamento
- [Carteira](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/carteira.md): saldo disponível e reservado
- [Rotas de teste](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/teste.md): rotas só do modo teste: avançar pedido e definir saldo

## Contrato

- [OpenAPI 3.1](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/openapi.yaml): contrato de máquina completo
- [Documentação completa num arquivo](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/llms-full.txt)
- [Documentação para pessoas](https://gubo.com.br/docs-api)

## Optional

- [Exemplos](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/exemplos.md): fluxo completo em cURL e clientes prontos em Node.js, Python e PHP
- [Integrar com IA](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/ia.md): llms.txt, OpenAPI, prompt recomendado e erros comuns de código gerado
- [Changelog](https://kx75xapy8azwdvdnd4brts7y098e5qvg.buildprintusercontent.com/gubo-api/latest/live/docs/changelog.md): política de versões e novidades