Referência da API

Todas as rotas, corpos e respostas.

3 min de leitura

Nesta página

GET /ping
POST /pontos-de-venda/ativar
GET /pontos-de-venda
GET /pontos-de-venda/{id}
POST /pontos-de-venda/{id}/desativar
POST /cobrancas
GET /cobrancas
GET /cobrancas/{id}
POST /cobrancas/{id}/cancelar
GET /eventos
Objetos
Cobranca
PontoDeVenda
Evento
Erro

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:

JSON

{
  "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
`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:

JSON

{
  "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
`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

JSON

{
  "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

JSON

{
  "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

JSON

{
  "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

JSON

{
  "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
}