Skip to content

Genius Returns - API reference (1.0.0)

Documentação e referências da api Genius Retuns.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Mock server

https://apidocs.geniusreturns.com.br/_mock/openapi/

Produção

https://integration.geniusreturns.com.br/

QA

https://integration-qa.geniusreturns.com.br/

Segurança

Operações de autenticação e segurança (obtenção do Bearer JWT).

Operations

Processos

Operações para obter, listar, filtrar e criar processos de troca ou devolução.

Operations

Obtém um processo por ID

Request

Security
BearerAuth
Path
id-processostringrequired

Identificador do processo.

curl -i -X GET \
  'https://apidocs.geniusreturns.com.br/_mock/openapi/v3/pvt/processo/{id-processo}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Sucesso

Bodyapplication/json
Datestring(date-time)required

Data e hora da resposta expressa em UTC

Resultobject(ProcessModel)

Objeto principal do processo

Recordsinteger

Registros retornados

HttpStatusstringrequired

Status http da requisição

Errobject(ApiResponseErro)

Conterá detalhes de um eventual erro

Response
application/json
{
  "dataHoraResposta": "2025-08-16T00:59:29.9238822Z",
  "registros": 1,
  "httpStatus": "200",
  "erroCodigo": null,
  "erroDescricao": null,
  "erroDetalhado": null,
  "erroTipo": null,
  "entidade": {
    "tipo": 0,
    "tipoFreteEstorno": 0,
    "valorDiferenca": -20,
    "mantenhaOItem": false,
    "status": 1,
    "numero": "GR-000123",
    "data": "2025-08-10T14:22:00Z",
    "tipoServicoLogistico": 0,
    "tipoServicoLogisticoDescricao": "Postagem em agência",
    "marketplace": false,
    "blocklist": false,
    "valeCompra": { … },
    "notasDevolucao": [ … ]
  }
}

Listar processos

Request

Retorna uma lista paginada de processos conforme filtros informados. Observação: os filtros também podem ser enviados no corpo (JSON), conforme exemplo de curl, caso seu cliente HTTP suporte body em requisições GET.

Security
BearerAuth
Query
pageNumberinteger>= 1

Número da página (inicia em 1).

pageSizeinteger>= 1

Quantidade de itens por página.

destring(date)

Data inicial (YYYY-MM-DD).

atestring(date)

Data final (YYYY-MM-DD).

statusinteger

Status do processo (Todos = -1, Pendente = 1, Concluido = 2, Cancelado = 3).

textoBuscastring

Número do pedido, nome/email do cliente ou nº de autorização.

lojaVirtualIdinteger(int64)

Id da loja virtual (sub account).

orderNumberstring

Número do pedido original na loja virtual.

estagioLogisticointeger

Estágio logístico do processo (EProcessLogisticStage).

estagioFinanceirointeger

Estágio financeiro do processo (EProcessFinancialStage).

estagioRatinginteger

Estágio rating do processo (EProcessRatingStage).

Bodyapplication/json
destring(date)

Data inicial (YYYY-MM-DD).

atestring(date)

Data final (YYYY-MM-DD).

statusinteger

Status do processo (Todos = -1, Pendente = 1, Concluido = 2, Cancelado = 3).

textoBuscastring

Número do pedido (e-commerce), nome/email do cliente ou nº de autorização.

lojaVirtualIdinteger(int64)

Id da loja virtual (sub account).

orderNumberstring

Número do pedido original na loja virtual.

estagioLogisticoNenhum (integer) or Pendente1 (integer) or Erro2 (integer) or Loja física3 (integer) or Autorizado4 (integer) or Postado ou coletado5 (integer) or Entregue6 (integer) or Parcialmente Entregue7 (integer)(int32)(EProcessLogisticStage)

Estágio logístico do processo.

Enum ValueDescription
0

Nenhum

1

Pendente

2

Erro

3

Loja física

4

Autorizado

5

Postado ou coletado

6

Entregue

7

Parcialmente Entregue

One of:

Estágio logístico do processo.

integer(int32)(Nenhum)

Estágio logístico do processo.

Enum ValueDescription
0

Nenhum

1

Pendente

2

Erro

3

Loja física

4

Autorizado

5

Postado ou coletado

6

Entregue

7

Parcialmente Entregue

estagioFinanceiroNenhum (integer) or Pendente1 (integer) or Reembolso parcial2 (integer) or Reembolso efetuado3 (integer) or Erro4 (integer)(int32)(EProcessFinancialStage)

Estágio financeiro do processo.

Enum ValueDescription
0

Nenhum

1

Pendente

2

Reembolso parcial

3

Reembolso efetuado

4

Erro

One of:

Estágio financeiro do processo.

integer(int32)(Nenhum)

Estágio financeiro do processo.

Enum ValueDescription
0

Nenhum

1

Pendente

2

Reembolso parcial

3

Reembolso efetuado

4

Erro

estagioRatingPendente (integer) or Parcial1 (integer) or Completo2 (integer)(int32)(EProcessRatingStage)

Estágio de rating do processo.

Enum ValueDescription
0

Pendente

1

Parcial

2

Completo

One of:

Estágio de rating do processo.

integer(int32)(Pendente)

Estágio de rating do processo.

Enum ValueDescription
0

Pendente

1

Parcial

2

Completo

curl --location --request GET 'https://integration.geniusreturns.com.br/v3/pvt/processo/listar?pageNumber=1&pageSize=10' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json' \
--data '{
    "de": "2025-05-01",
    "ate": "2025-05-28",
    "textoBusca": "12372-52025",
    "estagioLogistico": 3
}'

Responses

Lista de processos retornada com sucesso.

Bodyapplication/json
PageSizeinteger
TotalPagesinteger
CurrentPageinteger
TotalRecordsinteger
Datestring(date-time)required

Data e hora da resposta expressa em UTC

ResultArray of objects(ProcessModel)required

Entidade relacionada

Result[].​idinteger(int64)
Result[].​tipointeger

Tipo de Processo: Devolucao = 0, Troca = 1

Enum01
Result[].​tipoFreteEstornointeger

Tipo de estorno do frete (EPedidoItemEstorno): 0 ValeCompras, 1 Estorno, 2 Estorno automático

Enum012
Result[].​valorDiferencanumber(double)

0: não há diferença; >0: valor a receber do usuário; <0: valor a pagar ao usuário

Result[].​mantenhaOItemboolean or null

True quando a solicitação faz jus à funcionalidade KeepTheItem; do contrário, False

Result[].​statusinteger

Indefinido = -1, Iniciado = 0, Pendente = 1, Concluido = 2, Cancelado = 3

Enum-10123
Result[].​numerostring

Número da solicitação

Result[].​datastring(date-time)

Data da solicitação

Result[].​dadosBancariosDtoobject(DadosBancariosDTO)

Dados bancários do cliente para reembolso quando não for cartão de crédito

Result[].​notaFiscalDevolucaoobject or null

Nota fiscal de devolução

Result[].​pedidoobject(PedidoModel)
Result[].​lojaVirtualobject(LojaVirtualModel)

Loja virtual configurada na plataforma Genius

Result[].​valeCompraobject(ValeCompraModel)

Informações do vale-compra quando a forma de reembolso for vale

Result[].​autorizacoesLRArray of objects(AutorizacaoLogisticaReversaModel)

Coleção de autorizações de logística reversa

Result[].​lojaFisicaobject(LojaFisicaModel)

Dados da loja física quando a devolução ocorre em loja

Result[].​transportadoraobject(TransportadoraModel)

Dados da transportadora quando a forma de envio for transportadora

Result[].​tipoServicoLogisticointeger

Tipo de remessa reversa (EDTipoEntregaReversa): -1 Indefinido, 0 PostagemEmAgencia, 1 ColetaSimples, 2 ColetaSimultanea, 3 Expressa, 4 PostoDeColeta

Enum-101234
Result[].​tipoServicoLogisticoDescricaostring

Descrição do tipo de logística reversa

Result[].​lockerobject(LockerModel)

Dados do locker quando a postagem é em armário inteligente

Result[].​valorLogisticaPremiumnumber or null

Quando logística premium fornecida, valor a ser pago

Result[].​agenteobject(AgenteModel)
Result[].​marketplaceboolean

True se marketplace

Result[].​blocklistboolean

True se em Blocklist

Result[].​cashbackobject(CashbackDataModel)

Dados de cashback, quando cabível

Result[].​progressobject(ProcessProgressModel)

Estágios do processo

Result[].​notasDevolucaoArray of objects(ReturnNoteModel)

Coleção de notas de devolução associadas ao processo

Recordsinteger

Registros retornados

HttpStatusstring

Status http da requisição

Errobject(ApiResponseErro)

Conterá detalhes de um eventual erro

Response
application/json
{
  "PageSize": 0,
  "TotalPages": 0,
  "CurrentPage": 0,
  "TotalRecords": 0,
  "Date": "2019-08-24T14:15:22Z",
  "Result": [
    { … }
  ],
  "Records": 0,
  "HttpStatus": "string",
  "Err": {
    "ErroCodigo": "string",
    "ErroDescricao": "string"
  }
}

Integração do pedido ao fluxo de devolução

Request

Endpoint utilizado para integrar um pedido da loja virtual à plataforma Genius Returns. Um link será disponibilizado pela API e poderá ser utilizado para redirecionar o usuário solicitante à interface Genius Returns de solicitação de troca ou devolução, diretamente ao estágio de seleção itens.

Security
BearerAuth
Bodyapplication/jsonrequired
Pedidoobject(IntegrateRequestOrder)

Pedido para integração do fluxo de solicitação de troca ou devolução

curl -i -X POST \
  https://apidocs.geniusreturns.com.br/_mock/openapi/v3/pvt/processo/integrar/fluxo \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Pedido": {
      "PedidoNumero": "string",
      "PedidoStatus": "string",
      "PedidoId": "string",
      "Cliente": {
        "ClienteNome": "string",
        "ClienteEmail": "string",
        "ClienteTelefone": "string",
        "ClienteCelular": "string",
        "ClienteDocumento": "string",
        "ClienteEndereco": {
          "logradouro": "string",
          "numero": "string",
          "complemento": "string",
          "bairro": "string",
          "cidade": "string",
          "estado": "string",
          "cep": "string",
          "latitude": "string",
          "longitude": "string",
          "obs": "string"
        }
      },
      "PedidoData": "2019-08-24T14:15:22Z",
      "PedidoDataEntrega": "2019-08-24T14:15:22Z",
      "PedidoValorTotal": 0,
      "PedidoValorFrete": 0,
      "PedidoValorDesconto": 0,
      "Skus": [
        {
          "SkuId": "string",
          "SkuNome": "string",
          "SkuReferencia": "string",
          "SkuSellerReference": "string",
          "ProdutoId": "string",
          "ProductRef": "string",
          "ProdutoNome": "string",
          "Preco": 0,
          "PrecoDeLista": 0,
          "Quantidade": 0,
          "Peso": 0,
          "Altura": 0,
          "Largura": 0,
          "Comprimento": 0,
          "SellerId": "string",
          "DocaId": "string",
          "EstoqueId": "string",
          "ImagemAbsUrl": "string",
          "Variacoes": [
            {
              "Nome": "string",
              "Valores": [
                "string"
              ]
            }
          ],
          "InvoiceKey": "string"
        }
      ],
      "Transacoes": [
        {
          "TID": "string",
          "SellerNomeId": "string",
          "Data": "2019-08-24T14:15:22Z",
          "Pagamentos": [
            {
              "PId": "string",
              "TipoPagamento": 0,
              "TipoPagamentoDescricao": "string",
              "Valor": 0,
              "Parcelamento": 0,
              "ValorReferencia": 0,
              "TID": "string",
              "Nsu": "string",
              "Adquirente": "string",
              "Grupo": "string"
            }
          ]
        }
      ],
      "NotasFiscais": [
        {
          "Number": "string",
          "Series": "string",
          "AccessKey": "string",
          "XML": "string",
          "DanfeLink": "string",
          "Data": "2019-08-24T14:15:22Z",
          "File": "string"
        }
      ]
    }
  }'

Responses

OK

Bodyapplication/json
Datestring(date-time)

Data e hora da resposta expressa em UTC

Resultstring

Entidade relacionada

Recordsinteger(int32)

Registros retornados

HttpStatusstring

Status http da requisição

Errobject(ApiResponseErro)

Conterá detalhes de um eventual erro

Response
application/json
{
  "Date": "2019-08-24T14:15:22Z",
  "Result": "string",
  "Records": 0,
  "HttpStatus": "string",
  "Err": {
    "ErroCodigo": "string",
    "ErroDescricao": "string"
  }
}

Produtos

Ações relativas aos produtos constantes em uma solicitação de troca ou devolução.

Operations

Notas de devolução

Operações com notas fiscais de devolução.

Operations