API CotAgru — Documentação

Visão Geral

A API da CotAgru permite que sistemas parceiros enviem cotações em nome de produtores cadastrados. Use-a para automatizar o fluxo "criou pedido de compra no ERP → vira cotação na CotAgru → produtor seleciona vendedores e dispara WhatsApp".

Como funciona o fluxo:

Parceiro autentica com o token Bearer do produtor
Busca produtos no catálogo (GET /v1/produtos/buscar) para obter produtoId
Envia a cotação (POST /v1/cotacoes) — vira RASCUNHO no painel do produtor
Produtor abre o painel, seleciona vendedores e dispara WhatsApp
Parceiro consulta status (GET /v1/cotacoes/:id) — quando fechada, vê os vencedores

Como Começar

Cadastre uma conta de produtor em cotagru.com.br/registro (ou peça ao seu cliente final para cadastrar).
Solicite o token ao time CotAgru pelo WhatsApp (botão abaixo). Após validar o cadastro, enviamos seu token por canal seguro.
Use o token no header Authorization de toda chamada.
Teste com GET /v1/ping para confirmar que o token funciona.

Quer começar agora?

Fale com nosso time pelo WhatsApp e receba seu token de API em minutos.

Solicitar token via WhatsApp

Autenticação

Toda chamada usa Bearer token no header Authorization. O token tem o formato cotagru_sk_live_<random> e identifica unicamente uma conta de produtor.

Authorization: Bearer cotagru_sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Importante: só guardamos o hash SHA-256 do token. Se você perder, terá que solicitar rotação (revoga o atual e emite um novo) ao suporte CotAgru via WhatsApp. Por isso, guarde com cuidado quando receber.

Códigos de Erro

Toda resposta de erro segue o formato padronizado:

{
  "error": {
    "code": "string",       // identificador da máquina (ex: "invalid_token")
    "message": "string",    // mensagem human-readable em PT-BR
    "fields": [ ... ]       // (opcional) detalhes por campo em validation_error
  }
}

HTTP	code	Quando ocorre
`400`	`invalid_json`	Body não é JSON válido
`400`	`invalid_idempotency_key`	Idempotency-Key fora do formato (8–200 chars, [A-Za-z0-9_\-:.])
`401`	`missing_token`	Header Authorization ausente
`401`	`invalid_token_format`	Formato do token não bate com cotagru_sk_live_*
`401`	`invalid_token`	Token não encontrado (nunca foi emitido ou foi apagado)
`401`	`token_revoked`	Token foi revogado no painel
`401`	`token_expired`	Token expirou (raro — só se foi configurado com expiração)
`403`	`insufficient_scope`	Token não tem o escopo requerido pelo endpoint
`403`	`integration_disabled`	Flag de integração desativada para este usuário pelo admin
`404`	`cotacao_nao_encontrada`	Cotação inexistente ou de outra conta
`404`	`produto_nao_encontrado`	Um ou mais produtoIds inválidos no body do POST
`409`	`idempotency_key_reused`	Mesma Idempotency-Key usada com payload diferente
`422`	`validation_error`	Body falhou em alguma validação Zod (campos detalhados)
`429`	`rate_limit_exceeded`	Limite de req/min do token foi atingido
`500`	`internal_error`	Erro inesperado — reporte ao suporte com timestamp

Rate Limit

Cada token tem um limite de 60 requisições/minuto por padrão (janela deslizante de 60s). Quando excedido, retornamos 429 rate_limit_exceeded com header Retry-After: 60.

Toda resposta inclui:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47

Precisa de mais? Solicite aumento ao suporte indicando o caso de uso.

Escopos

Ao criar a chave, o produtor escolhe quais permissões liberar. Endpoints exigem escopos específicos:

Escopo	Permite
`read:produtos`	Buscar no catálogo de produtos do produtor
`write:cotacoes`	Criar novas cotações como RASCUNHO
`read:cotacoes`	Ler estado de cotações (incl. resultado/vencedores quando fechada)

`GET` /v1/ping

Healthcheck autenticado. Use para confirmar que o token está válido antes de chamadas mais pesadas.
Sem escopo específico — qualquer token ativo passa.

Request

curl https://www.cotagru.com.br/api/v1/ping \
  -H "Authorization: Bearer $COTAGRU_TOKEN"

Resposta 200

{
  "ok": true,
  "pong": "2026-06-03T18:42:11.123Z",
  "apiKeyId": "cmm8ccywx0000jp04tz3vip6a",
  "userId": "cmm8ccywx0000jp04tz3vip6b",
  "origem": "ConnectFarm",
  "scopes": ["read:produtos", "write:cotacoes", "read:cotacoes"],
  "rateLimit": 60
}

`GET` /v1/produtos/buscar

Lista produtos do catálogo do produtor. Use antes de criar a cotação para descobrir o produtoId. Filtra por nome, classe, concentração ou princípio ativo.
Escopo: read:produtos.

Query Params

Campo	Tipo	Descrição
`q`	string	Termo de busca (case-insensitive, até 100 caracteres). Bate em nome, concentração, classe e princípio ativo.
`limit`	number	Quantos retornar. Default `20`, máximo `100`.
`cursor`	string	ID do último item da página anterior. Envie o valor recebido em `paginacao.proximoCursor` para puxar a próxima página.

Request

curl "https://www.cotagru.com.br/api/v1/produtos/buscar?q=glifosato&limit=10" \
  -H "Authorization: Bearer $COTAGRU_TOKEN"

Resposta 200

{
  "data": [
    {
      "id": "cmm88t4nc00095w2w3igzi5c2",
      "nome": "Roundup Original",
      "unidade": "L",
      "origem": "AGROFIT",
      "concentracao": "480 g/L",
      "classe": "Herbicida",
      "formulacao": "Concentrado solúvel",
      "principiosAtivos": [
        {
          "nome": "Glifosato",
          "concentracao": "480",
          "unConcentracao": "g/L"
        }
      ]
    }
  ],
  "total": 1,
  "paginacao": {
    "limit": 10,
    "temMais": false,
    "proximoCursor": null
  }
}

`POST` /v1/cotacoes

Cria uma cotação como RASCUNHO. O produtor depois entra no painel para selecionar vendedores e disparar via WhatsApp.
Escopo: write:cotacoes.

Idempotency-Key (recomendado). Envie o header Idempotency-Key: <UUID> para que retries da mesma requisição (timeout, rede instável) não dupliquem a cotação. A 2ª chamada com mesma chave + mesmo body retorna a resposta original com header Idempotent-Replayed: true. Chave reusada com body diferente retorna 409.

Body

Campo	Tipo	Descrição
`titulo`obrig	string	Nome da cotação. Entre 3 e 200 caracteres.
`dataLimite`	ISO date	Até quando o vendedor pode responder. Ex: "2026-08-30".
`dataEntregaMaxima`	ISO date	Prazo máximo de entrega esperado.
`observacoes`	string	Observações gerais (até 2000 chars).
`datasPagamento`obrig	array	Datas em que o pagamento ocorrerá. Mínimo 1.
`datasPagamento[].data`obrig	ISO date	Ex: "2026-09-30".
`datasPagamento[].descricao`	string	Ex: "À vista", "30 dias". Até 200 caracteres.
`itens`obrig	array	Itens da cotação (1 a 200).
`itens[].produtoId`obrig	string	ID retornado por `GET /v1/produtos/buscar`.
`itens[].quantidade`	number	Um dos 3 obrigatório (> 0). Quantidade total a cotar.
`itens[].quantidadeVolume`	number	Um dos 3 obrigatório (> 0). Quantidade em litros/kg de produto.
`itens[].quantidadeHectares`	number	Um dos 3 obrigatório (> 0). Quantidade em hectares.
`itens[].unidade`obrig	string	Ex: "L", "KG", "DS". Até 10 chars.
`itens[].observacao`	string	Observação específica do item (até 500 chars).

Request

curl -X POST https://www.cotagru.com.br/api/v1/cotacoes \
  -H "Authorization: Bearer $COTAGRU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "titulo": "Cotação Soja Safra 26/27",
    "dataLimite": "2026-08-30",
    "dataEntregaMaxima": "2026-10-15",
    "observacoes": "Entrega na Fazenda Areal",
    "datasPagamento": [
      { "data": "2026-09-30", "descricao": "30 dias" },
      { "data": "2026-12-30", "descricao": "120 dias" }
    ],
    "itens": [
      {
        "produtoId": "cmm88t4nc00095w2w3igzi5c2",
        "quantidade": 5000,
        "unidade": "L",
        "observacao": "Marca preferida: Roundup"
      },
      {
        "produtoId": "cmn684x6d0000l204q7680i01",
        "quantidadeHectares": 1200,
        "unidade": "DS"
      }
    ]
  }'

Resposta 201

{
  "id": "cmn7abc12340001xyz",
  "status": "RASCUNHO",
  "titulo": "Cotação Soja Safra 26/27",
  "criadaEm": "2026-06-03T18:42:11.123Z",
  "totalItens": 2,
  "linkPainel": "https://www.cotagru.com.br/dashboard/cotacoes/cmn7abc12340001xyz",
  "proximosPassos": "A cotação foi criada como RASCUNHO. Abra o link no painel para selecionar vendedores e disparar via WhatsApp."
}

Resposta 422 (payload inválido)

{
  "error": {
    "code": "validation_error",
    "message": "Payload inválido",
    "fields": [
      { "path": "titulo", "message": "titulo deve ter ao menos 3 caracteres", "code": "too_small" },
      { "path": "datasPagamento", "message": "Informe ao menos 1 data de pagamento", "code": "too_small" }
    ]
  }
}

Resposta 404 (produto não encontrado)

{
  "error": {
    "code": "produto_nao_encontrado",
    "message": "Um ou mais produtoIds não existem ou não pertencem à conta do token",
    "produtoIdsInvalidos": ["xyz_nao_existe"]
  }
}

`GET` /v1/cotacoes/:id

Lê o estado atual de uma cotação. Quando o status é FECHADA ou FECHADA_PARCIAL, o campo resultado traz os vencedores com itens, preços, datas de pagamento e distribuição por fazenda.
Escopo: read:cotacoes.

Request

curl https://www.cotagru.com.br/api/v1/cotacoes/cmn7abc12340001xyz \
  -H "Authorization: Bearer $COTAGRU_TOKEN"

Resposta 200 — Em andamento

{
  "id": "cmn7abc12340001xyz",
  "numeroCotacao": "2026021",
  "titulo": "Cotação Soja Safra 26/27",
  "status": "ABERTA",
  "criadaEm": "2026-06-03T18:42:11.123Z",
  "atualizadaEm": "2026-06-03T19:01:00.000Z",
  "dataLimite": "2026-08-30T00:00:00.000Z",
  "dataEntregaMaxima": "2026-10-15T00:00:00.000Z",
  "observacoes": "Entrega na Fazenda Areal",
  "totalItens": 2,
  "datasPagamento": [
    { "data": "2026-09-30", "descricao": "30 dias" },
    { "data": "2026-12-30", "descricao": "120 dias" }
  ],
  "itens": [
    {
      "produtoId": "cmm88t4nc00095w2w3igzi5c2",
      "produtoNome": "Roundup Original",
      "quantidade": 5000,
      "quantidadeVolume": 0,
      "quantidadeHectares": 0,
      "unidade": "L",
      "observacao": "Marca preferida: Roundup"
    },
    {
      "produtoId": "cmn684x6d0000l204q7680i01",
      "produtoNome": "Dessecante Premium",
      "quantidade": 0,
      "quantidadeVolume": 0,
      "quantidadeHectares": 1200,
      "unidade": "DS",
      "observacao": null
    }
  ],
  "linkPainel": "https://www.cotagru.com.br/dashboard/cotacoes/cmn7abc12340001xyz",
  "resultado": null
}

Resposta 200 — Fechada (com vencedores)

{
  "id": "cmn7abc12340001xyz",
  "numeroCotacao": "2026021",
  "titulo": "Cotação Soja Safra 26/27",
  "status": "FECHADA",
  "criadaEm": "2026-06-03T18:42:11.123Z",
  "atualizadaEm": "2026-06-10T14:22:31.000Z",
  "dataLimite": "2026-08-30T00:00:00.000Z",
  "dataEntregaMaxima": "2026-10-15T00:00:00.000Z",
  "observacoes": "Entrega na Fazenda Areal",
  "totalItens": 2,
  "datasPagamento": [
    { "data": "2026-09-30", "descricao": "30 dias" },
    { "data": "2026-12-30", "descricao": "120 dias" }
  ],
  "itens": [ /* mesmo shape do exemplo "Em andamento" acima */ ],
  "linkPainel": "https://www.cotagru.com.br/dashboard/cotacoes/cmn7abc12340001xyz",
  "resultado": {
    "totalGeral": 28450.00,
    "dataFechamento": "2026-06-10T14:22:31.000Z",
    "observacaoFechamento": "Fechado com 2 vendedores",
    "vencedores": [
      {
        "vendedorNome": "Agro XYZ",
        "telefone": "5562999999999",
        "totalGeral": 18450.00,
        "itens": [
          {
            "produtoNome": "Roundup Original",
            "quantidade": 5000,
            "unidade": "L",
            "preco": 3.20,
            "total": 16000.00,
            "dataPagamento": "2026-09-30",
            "distribuicaoFazendas": [
              { "fazenda": "Fazenda Areal", "quantidade": 3000 },
              { "fazenda": "Fazenda Boa Vista", "quantidade": 2000 }
            ]
          }
        ]
      }
    ]
  }
}

Status possíveis: RASCUNHO ABERTA EM_ANDAMENTO FECHADA FECHADA_PARCIAL CANCELADA

Suporte

Dúvidas técnicas, solicitar aumento de rate limit, reportar bug:

Email: contato@cotagru.com.br

Site: cotagru.com.br

Esta documentação reflete a versão estável v1 da API. Mudanças incompatíveis serão feitas em v2; mudanças aditivas (campos novos) são feitas em v1 e listadas no changelog. Última atualização: 03/06/2026.

API CotAgru v1

Visão Geral

Como Começar

Autenticação

Códigos de Erro

Rate Limit

Escopos

GET /v1/ping

Request

Resposta 200

GET /v1/produtos/buscar

Query Params

Request

Resposta 200

POST /v1/cotacoes

Body

Request

Resposta 201

Resposta 422 (payload inválido)

Resposta 404 (produto não encontrado)

GET /v1/cotacoes/:id

Request

Resposta 200 — Em andamento

Resposta 200 — Fechada (com vencedores)

Suporte

`GET` /v1/ping

`GET` /v1/produtos/buscar

`POST` /v1/cotacoes

`GET` /v1/cotacoes/:id