MoedaClip

Guia de integração para ERPs e PDVs

O MoedaClip mostra ao dono da rede o movimento das lojas em tempo real — vendas por hora, produtos, setores, formas de pagamento e comparativo entre filiais. Todo dado exibido vem exclusivamente da sua integração: o sistema da loja envia as vendas para a API e o app faz o resto.

1O que você recebe para integrar

Token de integração da loja — uma credencial no formato mclip_…, única por loja (matriz ou filial). É ela que autoriza o envio de dados daquela loja. Fornecida por nós junto com este guia.

Collection do Postman — todos os endpoints prontos. Importe no Postman ou Insomnia e cole o token na variável api_token.

⬇ Baixar collection do Postman

Este guia — referência dos endpoints, campos e regras.

Guarde o token como uma senha. Ele deve viver na retaguarda/servidor do ERP — nunca em site público ou aplicativo distribuído. Se vazar, nós geramos outro na hora (o antigo para de funcionar imediatamente).

2A API em 30 segundos

Base URL: https://www.moedaclip.com.br/api

Todos os endpoints são POST com corpo JSON. Único header necessário: Content-Type: application/json. A credencial vai no corpo, no campo p_token.

POST/ping— valida o token e identifica a loja

POST/sales— envia ou atualiza um lote de vendas (até 500)

POST/sales/delete— expurga vendas (somente correções)

POST/fiscal— atualiza o status fiscal (NF-e/NFC-e) das vendas

3Valide a credencial

curl -X POST "https://www.moedaclip.com.br/api/ping" \
  -H "Content-Type: application/json" \
  -d '{ "p_token": "mclip_SEU_TOKEN_AQUI" }'

# → { "ok": true, "company": "NOME DA LOJA", ... }

4Envie as vendas

Uma chamada leva um lote de até 500 vendas. Cada venda carrega seus itens e pagamentos:

POST /sales
{
  "p_token": "mclip_SEU_TOKEN_AQUI",
  "p_sales": [
    {
      "external_id": "cupom-123456",          // nº do cupom no SEU sistema
      "sold_at": "2026-09-02T14:30:00-04:00", // ISO 8601 COM fuso horário
      "status": "completed",                   // ou "canceled"
      "total": 120.00,
      "discount": 0,
      "customer": "opcional",
      "items": [
        {
          "product_code": "P001",
          "product_name": "VESTIDO MIDI PLUS",
          "sector_name": "VESTIDOS",          // alimenta o relatório "Por Setor"
          "quantity": 2,
          "unit_price": 60.00,
          "total": 120.00,
          "unit_cost": 32.00,                  // alimenta lucro bruto/custo médio
          "status": "sold"                     // "canceled" | "returned"
        }
      ],
      "payments": [
        { "method_name": "PIX", "amount": 120.00 }
      ]
    }
  ]
}

// → { "ok": true, "received": 1, "created": 1, "updated": 0 }

Campos obrigatórios

Campo	Onde	Regra
`external_id` obrigatório	venda	Identificador da venda no seu sistema, único por loja
`sold_at` obrigatório	venda	ISO 8601 com offset de fuso (ex.: `-04:00`)
`product_name` obrigatório	item	Nome do produto
`method_name` obrigatório	pagamento	Nome da forma de pagamento

Todos os demais campos são opcionais e têm cálculo automático quando omitidos (ex.: cost_total soma dos custos dos itens; items_count soma das quantidades). Itens e pagamentos são recomendados: sem eles os relatórios de produtos/setores e formas de pagamento ficam vazios.

4bEnvie o fiscal (se a loja emite NF-e/NFC-e)

Toda venda entra como MEI (sem nota emitida). Para as vendas com nota, informe a situação via /fiscal — o painel mostra o vendido dividido em Autorizadas / Canceladas / Pendentes / MEI:

POST /fiscal
{
  "p_token": "mclip_SEU_TOKEN_AQUI",
  "p_fiscal": [
    {
      "external_id": "cupom-123456",   // a mesma chave enviada em /sales
      "status": "authorized",           // "canceled" | "pending" | "mei"
      "model": "65",                    // 55 = NF-e, 65 = NFC-e
      "number": "123456",
      "key": "5126...0000",             // chave de acesso (opcional)
      "issued_at": "2026-09-02T14:31:00-04:00"
    }
  ]
}

// → { "ok": true, "received": 1, "updated": 1, "not_found": 0 }

Mudou a situação da nota (autorizou, cancelou)? Reenvie o mesmo external_id com o novo status. Aliases aceitos: autorizada/cancelada/pendente/sem_nota.

5Regras de ouro

Idempotência total. Reenviar o mesmo external_id atualiza a venda (itens e pagamentos são substituídos). Pode reenviar sem medo — nunca duplica.
Cancelou no PDV? Reenvie a venda com "status": "canceled". Ela passa a contar em "Canceladas".
Devolução de item: reenvie a venda com o item marcado "status": "returned".
Frequência sugerida: a cada venda finalizada, ou em lote a cada 1–5 minutos. O lote é atômico: se der erro, corrija e reenvie o lote inteiro.
Carga histórica: pode enviar o passado em lotes de 500 — os relatórios ficam retroativos na hora.
Aliases em português aceitos: efetivada/cancelada na venda; vendido/cancelado/devolvido no item.

6Erros

Erros retornam HTTP 400 com a causa no campo message:

Mensagem	Como resolver
`Token de API inválido ou empresa inativa`	Confira o token (pode ter sido regenerado) ou fale conosco
`Venda #N: campo external_id é obrigatório`	Toda venda do lote precisa de `external_id`
`sold_at é obrigatório em formato ISO 8601`	Envie data com offset: `2026-09-02T14:30:00-04:00`
`Máximo de 500 vendas por chamada`	Divida o lote

7Confira no app

Depois do primeiro envio, abra www.moedaclip.com.br com o usuário fornecido: as vendas aparecem no dashboard em segundos (botão de atualizar no topo). Se o número do app bater com o do PDV, a integração está pronta. ✔