Baixar (.md)OpenAPI

Referência da API

Endereço base: https://moedanobre.com/api/v1 · Autenticação: Authorization: Bearer <chave> · OpenAPI 3.1 (JSON)

GET /ping

A chave funciona?

HTTP Resposta
200 Ping — OK
401 Erro — CHAVE_INVALIDA · CHAVE_REVOGADA · PARCEIRO_SUSPENSO · PRODUCAO_NAO_LIBERADA · APLICATIVO_DESATIVADO
403 Erro — CHAVE_EM_NAVEGADOR
429 Erro — LIMITE_EXCEDIDO
500 Erro — ERRO_INTERNO

POST /pontos-de-venda/ativar

Ligar um caixa com o código de ativação

Produção: código XXXX-XXXX gerado pelo gerente da loja. Testes: código T-XXXX-XXXX gerado no portal. Uso único; 5 códigos errados por chave em 1 hora bloqueiam por 1 hora.

Corpo:

{
  "type": "object",
  "properties": {
    "codigoAtivacao": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "identificadorExterno": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$"
    },
    "nome": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    }
  },
  "required": [
    "codigoAtivacao",
    "identificadorExterno"
  ],
  "additionalProperties": false
}
HTTP Resposta
201 PontoDeVenda — Caixa ativo
400 Erro — VALIDACAO · CAMPO_DESCONHECIDO
401 Erro — CHAVE_INVALIDA · CHAVE_REVOGADA · PARCEIRO_SUSPENSO · PRODUCAO_NAO_LIBERADA · APLICATIVO_DESATIVADO
403 Erro — CHAVE_EM_NAVEGADOR
409 Erro — PDV_JA_ATIVO
410 Erro — CODIGO_ATIVACAO_EXPIRADO
422 Erro — CODIGO_ATIVACAO_INVALIDO · LOJA_INATIVA
429 Erro — LIMITE_EXCEDIDO
500 Erro — ERRO_INTERNO

GET /pontos-de-venda

Listar os caixas

Parâmetro Onde Obrigatório Descrição
status query não
cursor query não
limite query não
HTTP Resposta
200 PaginaPontosDeVenda — Página
400 Erro — VALIDACAO
401 Erro — CHAVE_INVALIDA · CHAVE_REVOGADA · PARCEIRO_SUSPENSO · PRODUCAO_NAO_LIBERADA · APLICATIVO_DESATIVADO
403 Erro — CHAVE_EM_NAVEGADOR
429 Erro — LIMITE_EXCEDIDO
500 Erro — ERRO_INTERNO

GET /pontos-de-venda/{id}

Um caixa

Parâmetro Onde Obrigatório Descrição
id caminho sim Id do caixa
HTTP Resposta
200 PontoDeVenda — OK
401 Erro — CHAVE_INVALIDA · CHAVE_REVOGADA · PARCEIRO_SUSPENSO · PRODUCAO_NAO_LIBERADA · APLICATIVO_DESATIVADO
403 Erro — CHAVE_EM_NAVEGADOR
404 Erro — PDV_NAO_ENCONTRADO
429 Erro — LIMITE_EXCEDIDO
500 Erro — ERRO_INTERNO

POST /pontos-de-venda/{id}/desativar

Desligar um caixa (cancela a pendente dele)

Parâmetro Onde Obrigatório Descrição
id caminho sim Id do caixa
HTTP Resposta
200 PontoDeVenda — Caixa desligado
401 Erro — CHAVE_INVALIDA · CHAVE_REVOGADA · PARCEIRO_SUSPENSO · PRODUCAO_NAO_LIBERADA · APLICATIVO_DESATIVADO
403 Erro — CHAVE_EM_NAVEGADOR
404 Erro — PDV_NAO_ENCONTRADO
429 Erro — LIMITE_EXCEDIDO
500 Erro — ERRO_INTERNO

POST /cobrancas

Criar uma cobrança

Uma cobrança pendente por caixa. Com cancelarPendenteAnterior=true a anterior é cancelada (se o cliente não tiver acabado de pagá-la).

Parâmetro Onde Obrigatório Descrição
Idempotency-Key cabeçalho sim Único por cobrança que você quer criar (ex.: o id do cupom). Repetir com o mesmo corpo devolve a mesma cobrança.
Moeda-Nobre-Teste-Cenario cabeçalho não Só com chave de teste.

Corpo:

{
  "type": "object",
  "properties": {
    "pontoDeVendaId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "valorCentavos": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9999999
    },
    "referenciaExterna": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "expiraEmSegundos": {
      "default": 300,
      "type": "integer",
      "minimum": 60,
      "maximum": 900
    },
    "metadados": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1,
        "maxLength": 40
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 100
      }
    },
    "cancelarPendenteAnterior": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "pontoDeVendaId",
    "valorCentavos"
  ],
  "additionalProperties": false
}
HTTP Resposta
200 Cobranca — Repetição com a mesma Idempotency-Key (cabeçalho Idempotent-Replayed: true)
201 Cobranca — Cobrança criada (com o QR)
400 Erro — VALIDACAO · CAMPO_DESCONHECIDO · IDEMPOTENCY_KEY_OBRIGATORIA · CENARIO_SO_EM_TESTE · CENARIO_INVALIDO
401 Erro — CHAVE_INVALIDA · CHAVE_REVOGADA · PARCEIRO_SUSPENSO · PRODUCAO_NAO_LIBERADA · APLICATIVO_DESATIVADO
403 Erro — CHAVE_EM_NAVEGADOR
404 Erro — PDV_NAO_ENCONTRADO
409 Erro — COBRANCA_PENDENTE_EXISTE · COBRANCA_NAO_PENDENTE · REQUISICAO_EM_ANDAMENTO
422 Erro — IDEMPOTENCY_CONFLITO · PDV_INATIVO · LOJA_INATIVA · VINCULO_REVOGADO
429 Erro — LIMITE_EXCEDIDO
500 Erro — ERRO_INTERNO

GET /cobrancas

Listar cobranças

Parâmetro Onde Obrigatório Descrição
pontoDeVendaId query não
status query não
criadoDe query não
criadoAte query não
referenciaExterna query não
cursor query não
limite query não
HTTP Resposta
200 PaginaCobrancas — Página
400 Erro — VALIDACAO
401 Erro — CHAVE_INVALIDA · CHAVE_REVOGADA · PARCEIRO_SUSPENSO · PRODUCAO_NAO_LIBERADA · APLICATIVO_DESATIVADO
403 Erro — CHAVE_EM_NAVEGADOR
429 Erro — LIMITE_EXCEDIDO
500 Erro — ERRO_INTERNO

GET /cobrancas/{id}

Uma cobrança — com ?aguardar=N espera até N segundos por uma mudança (long-poll)

Parâmetro Onde Obrigatório Descrição
id caminho sim Id da cobrança
aguardar query não
semImagem query não
HTTP Resposta
200 Cobranca — OK
400 Erro — VALIDACAO
401 Erro — CHAVE_INVALIDA · CHAVE_REVOGADA · PARCEIRO_SUSPENSO · PRODUCAO_NAO_LIBERADA · APLICATIVO_DESATIVADO
403 Erro — CHAVE_EM_NAVEGADOR
404 Erro — COBRANCA_NAO_ENCONTRADA
429 Erro — LIMITE_EXCEDIDO
500 Erro — ERRO_INTERNO

POST /cobrancas/{id}/cancelar

Cancelar uma cobrança pendente

Parâmetro Onde Obrigatório Descrição
id caminho sim Id da cobrança
HTTP Resposta
200 Cobranca — Cancelada
401 Erro — CHAVE_INVALIDA · CHAVE_REVOGADA · PARCEIRO_SUSPENSO · PRODUCAO_NAO_LIBERADA · APLICATIVO_DESATIVADO
403 Erro — CHAVE_EM_NAVEGADOR
404 Erro — COBRANCA_NAO_ENCONTRADA
409 Erro — COBRANCA_NAO_PENDENTE
429 Erro — LIMITE_EXCEDIDO
500 Erro — ERRO_INTERNO

GET /eventos

Eventos dos últimos 30 dias, em ordem (conciliação / quem não recebe webhook)

Parâmetro Onde Obrigatório Descrição
apos query não
limite query não
HTTP Resposta
200 PaginaEventos — Página
400 Erro — VALIDACAO
401 Erro — CHAVE_INVALIDA · CHAVE_REVOGADA · PARCEIRO_SUSPENSO · PRODUCAO_NAO_LIBERADA · APLICATIVO_DESATIVADO
403 Erro — CHAVE_EM_NAVEGADOR
404 Erro — RECURSO_NAO_ENCONTRADO
429 Erro — LIMITE_EXCEDIDO
500 Erro — ERRO_INTERNO

Objetos

Cobranca

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id da cobrança (é o `tid` do QR)"
    },
    "status": {
      "type": "string",
      "enum": [
        "PENDENTE",
        "PAGA",
        "CANCELADA",
        "EXPIRADA",
        "ESTORNADA"
      ]
    },
    "valorCentavos": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "pontoDeVendaId": {
      "type": "string"
    },
    "lojaId": {
      "type": "string"
    },
    "referenciaExterna": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "metadados": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "qrCode": {
      "description": "Só enquanto PENDENTE",
      "type": "object",
      "properties": {
        "conteudo": {
          "type": "string",
          "description": "Texto do QR — desenhe com qualquer biblioteca de QR"
        },
        "imagemPng": {
          "description": "data:image/png;base64,… (omitida com ?semImagem=true)",
          "type": "string"
        }
      },
      "required": [
        "conteudo"
      ],
      "additionalProperties": false
    },
    "criadoEm": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
        },
        {
          "type": "null"
        }
      ]
    },
    "expiraEm": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
        },
        {
          "type": "null"
        }
      ]
    },
    "pagaEm": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
        },
        {
          "type": "null"
        }
      ]
    },
    "canceladaEm": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
        },
        {
          "type": "null"
        }
      ]
    },
    "expiradaEm": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
        },
        {
          "type": "null"
        }
      ]
    },
    "estornadaEm": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
        },
        {
          "type": "null"
        }
      ]
    },
    "ambiente": {
      "type": "string",
      "enum": [
        "TESTE",
        "PRODUCAO"
      ]
    }
  },
  "required": [
    "id",
    "status",
    "valorCentavos",
    "pontoDeVendaId",
    "lojaId",
    "referenciaExterna",
    "metadados",
    "criadoEm",
    "expiraEm",
    "pagaEm",
    "canceladaEm",
    "expiradaEm",
    "estornadaEm",
    "ambiente"
  ],
  "additionalProperties": false
}

PontoDeVenda

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "identificadorExterno": {
      "type": "string"
    },
    "nome": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "ATIVO",
        "DESATIVADO"
      ]
    },
    "loja": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "nomeFantasia": {
          "type": "string"
        },
        "cidade": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "estado": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "nomeFantasia",
        "cidade",
        "estado"
      ],
      "additionalProperties": false
    },
    "ativadoEm": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
        },
        {
          "type": "null"
        }
      ]
    },
    "desativadoEm": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
        },
        {
          "type": "null"
        }
      ]
    },
    "ambiente": {
      "type": "string",
      "enum": [
        "TESTE",
        "PRODUCAO"
      ]
    }
  },
  "required": [
    "id",
    "identificadorExterno",
    "nome",
    "status",
    "loja",
    "ativadoEm",
    "desativadoEm",
    "ambiente"
  ],
  "additionalProperties": false
}

Evento

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "evt_… — use para não processar o mesmo evento duas vezes"
    },
    "tipo": {
      "type": "string",
      "enum": [
        "cobranca.paga",
        "cobranca.cancelada",
        "cobranca.expirada",
        "cobranca.estornada",
        "ponto_de_venda.desativado",
        "ponto_de_venda.reativado",
        "ping"
      ]
    },
    "criadoEm": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
        },
        {
          "type": "null"
        }
      ]
    },
    "ambiente": {
      "type": "string",
      "enum": [
        "TESTE",
        "PRODUCAO"
      ]
    },
    "dados": {
      "type": "object",
      "properties": {
        "cobranca": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Id da cobrança (é o `tid` do QR)"
            },
            "status": {
              "type": "string",
              "enum": [
                "PENDENTE",
                "PAGA",
                "CANCELADA",
                "EXPIRADA",
                "ESTORNADA"
              ]
            },
            "valorCentavos": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "pontoDeVendaId": {
              "type": "string"
            },
            "lojaId": {
              "type": "string"
            },
            "referenciaExterna": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "metadados": {
              "anyOf": [
                {
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": "string"
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "qrCode": {
              "description": "Só enquanto PENDENTE",
              "type": "object",
              "properties": {
                "conteudo": {
                  "type": "string",
                  "description": "Texto do QR — desenhe com qualquer biblioteca de QR"
                },
                "imagemPng": {
                  "description": "data:image/png;base64,… (omitida com ?semImagem=true)",
                  "type": "string"
                }
              },
              "required": [
                "conteudo"
              ],
              "additionalProperties": false
            },
            "criadoEm": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
                },
                {
                  "type": "null"
                }
              ]
            },
            "expiraEm": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
                },
                {
                  "type": "null"
                }
              ]
            },
            "pagaEm": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
                },
                {
                  "type": "null"
                }
              ]
            },
            "canceladaEm": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
                },
                {
                  "type": "null"
                }
              ]
            },
            "expiradaEm": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
                },
                {
                  "type": "null"
                }
              ]
            },
            "estornadaEm": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
                },
                {
                  "type": "null"
                }
              ]
            },
            "ambiente": {
              "type": "string",
              "enum": [
                "TESTE",
                "PRODUCAO"
              ]
            }
          },
          "required": [
            "id",
            "status",
            "valorCentavos",
            "pontoDeVendaId",
            "lojaId",
            "referenciaExterna",
            "metadados",
            "criadoEm",
            "expiraEm",
            "pagaEm",
            "canceladaEm",
            "expiradaEm",
            "estornadaEm",
            "ambiente"
          ],
          "additionalProperties": false
        },
        "pontoDeVenda": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "identificadorExterno": {
              "type": "string"
            },
            "nome": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "ATIVO",
                "DESATIVADO"
              ]
            },
            "loja": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "nomeFantasia": {
                  "type": "string"
                },
                "cidade": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "estado": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "id",
                "nomeFantasia",
                "cidade",
                "estado"
              ],
              "additionalProperties": false
            },
            "ativadoEm": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
                },
                {
                  "type": "null"
                }
              ]
            },
            "desativadoEm": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "Data ISO-8601 com fuso de Brasília, ex. 2026-09-25T14:03:11-03:00"
                },
                {
                  "type": "null"
                }
              ]
            },
            "ambiente": {
              "type": "string",
              "enum": [
                "TESTE",
                "PRODUCAO"
              ]
            }
          },
          "required": [
            "id",
            "identificadorExterno",
            "nome",
            "status",
            "loja",
            "ativadoEm",
            "desativadoEm",
            "ambiente"
          ],
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "tipo",
    "criadoEm",
    "ambiente",
    "dados"
  ],
  "additionalProperties": false
}

Erro

{
  "type": "object",
  "properties": {
    "erro": {
      "type": "object",
      "properties": {
        "codigo": {
          "type": "string",
          "enum": [
            "VALIDACAO",
            "CAMPO_DESCONHECIDO",
            "IDEMPOTENCY_KEY_OBRIGATORIA",
            "CENARIO_SO_EM_TESTE",
            "CENARIO_INVALIDO",
            "CHAVE_INVALIDA",
            "CHAVE_REVOGADA",
            "PARCEIRO_SUSPENSO",
            "PRODUCAO_NAO_LIBERADA",
            "APLICATIVO_DESATIVADO",
            "CHAVE_EM_NAVEGADOR",
            "PDV_NAO_ENCONTRADO",
            "COBRANCA_NAO_ENCONTRADA",
            "RECURSO_NAO_ENCONTRADO",
            "METODO_NAO_PERMITIDO",
            "COBRANCA_PENDENTE_EXISTE",
            "COBRANCA_NAO_PENDENTE",
            "REQUISICAO_EM_ANDAMENTO",
            "PDV_JA_ATIVO",
            "CODIGO_ATIVACAO_EXPIRADO",
            "CORPO_GRANDE",
            "CONTENT_TYPE",
            "IDEMPOTENCY_CONFLITO",
            "PDV_INATIVO",
            "LOJA_INATIVA",
            "VINCULO_REVOGADO",
            "CODIGO_ATIVACAO_INVALIDO",
            "LIMITE_EXCEDIDO",
            "ERRO_INTERNO",
            "INDISPONIVEL"
          ]
        },
        "mensagem": {
          "type": "string"
        },
        "detalhes": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        "requestId": {
          "type": "string",
          "description": "Mande este id ao suporte"
        }
      },
      "required": [
        "codigo",
        "mensagem",
        "requestId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "erro"
  ],
  "additionalProperties": false
}