TL;DR

  • 브라질 전자 세금 문서인 NF-e(55), NFC-e(65), CT-e(57), MDF-e(58)의 SEFAZ 웹서비스를 Postman 컬렉션으로 정리해 SOAP 1.2 요청과 변수 설정을 제공함
  • 컬렉션은 5개 폴더에 걸친 29개 항목으로 구성되며, 각 요청에 조립된 SOAP 1.2 envelope와 {{}} 변수를 포함함
  • CT-e와 MDF-e의 두 DFe 배포 서비스는 2026년 09월 12일 운영 환경의 SEFAZ에서 cStat 137로 검증됨
  • XMLDSig 서명이 필요한 승인·이벤트·무효화 서비스와 서명이 필요 없는 조회·상태·배포 서비스가 구분됨
  • 기본 범위는 대부분의 주를 지원하는 SVRS URL과 배포용 국가 환경이며, 주별 자체 승인 기관은 URL을 직접 교체해야 함

SEFAZ 웹서비스 카탈로그

  • 브라질 전자 세금 문서 웹서비스의 완전하고 문서화된 Postman 컬렉션임.
  • 대상 문서는 다음과 같음.
  • NF-e(55)
  • NFC-e(65)
  • CT-e(57)
  • MDF-e(58)
  • 파일 위치는 postman/SEFAZ-Webservices-Catalogo.postman_collection.json임.
  • 모델별 폴더 1개와 이벤트 참고 폴더를 포함한 5개 폴더, 29개 항목으로 구성됨.

존재 이유

  • SEFAZ 연동에는 MOC NF-e/NFC-e 4.00, CT-e 4.00, MDF-e 3.00b, NT 2015.002 매뉴얼과 승인 기관 포털을 찾아 서비스별 URL, SOAP envelope, 개별 특성을 확인하는 작업이 필요함.
  • 이 컬렉션은 각 요청에 조립된 SOAP 1.2 envelope와 {{}} 변수를 포함해 해당 정보를 바로 사용할 수 있도록 구성됨.
  • CT-e와 MDF-e의 두 DFe 배포 서비스는 2026년 09월 12일 SEFAZ 운영 환경에서 검증됐으며, cStat 137 상태로 [OK testado] 표시됨.

Postman 설정

  • Import > postman/SEFAZ-Webservices-Catalogo.postman_collection.json 순서로 컬렉션을 가져옴.
  • Settings > Certificates > Add Certificate에서 호스트별로 e-CNPJ A1(.pfx + 비밀번호) 인증서를 추가함.
  • 배포 서비스 호스트는 www1.cte.fazenda.gov.br, mdfe.svrs.rs.gov.br, mdfe-homologacao.svrs.rs.gov.br임.
  • Settings > General에서 SSL certificate verification을 끔.
  • ICP-Brasil 인증 기관이 Postman의 신뢰 저장소에 포함되지 않기 때문임.
  • 각 요청의 설명에 적힌 homolog 또는 prod URL을 {{url}} 변수에 복사하고 cnpj, cUF, tpAmb 등을 조정한 뒤 실행함.

규칙

  • 이름에 [cadeado]가 붙은 요청은 데이터 XML에 XMLDSig 서명이 필요함.
  • 대상은 승인, 이벤트, 무효화 서비스임.
  • Postman은 XML에 서명하지 않으므로 별도 서명 도구나 자체 코드를 사용함.
  • 조회, 상태 확인, 배포 서비스에는 XML 서명이 필요하지 않음.
  • [OK testado]는 SEFAZ에서 cStat 137로 검증된 항목을 뜻함.
  • 모든 서비스는 SOAP 1.2를 사용하며, action은 SOAP 헤더가 아니라 Content-Type에 포함됨.

실제 테스트에서 확인된 차이

  • CT-e 배포(국가 환경)는 cUFAutor가 포함된 distDFeInt를 사용하며, cteDistDFeInteresse > cteDadosMsg 래퍼와 cabecMsg가 없음.
  • MDF-e 배포(SVRS)는 cUFAutor가 없는 distDFeInt를 사용함.
  • cUF는 헤더의 mdfeCabecMsg에 들어감.
  • 본문에는 mdfeDadosMsg가 직접 들어감.
  • distNSU와 consNSU만 제공되며 consChNSU는 없음.
  • NF-e 배포(국가 환경)는 cUFAutor가 포함된다는 점에서 CT-e와 같으며, 버전은 1.01임.
  • CT-e 4.00 승인은 동기 방식만 제공됨.
  • 국가 서비스 목록에 비동기 일괄 처리와 무효화는 없음.
  • 사용되는 서비스는 SincV4, OSV4, GTVeV4임.
  • MDF-e 3.00 승인은 GZip+Base64로 압축·인코딩된 데이터 영역을 포함하는 동기 방식임.
  • NFC-e는 CSC + QR Code가 필요하며, infNFeSupl에 관련 정보가 들어감.
  • SVC는 제공되지 않으며, 오프라인 비상 운영은 tpEmis=9임.
  • AM, GO, MS, MT, PR, RS, SP는 자체 환경을 보유함.

범위와 한계

  • 기본 URL은 대부분의 주를 지원하는 SVRS와 배포 서비스용 국가 환경임.
  • 27개 주를 각각 다루지는 않으며, 자체 승인 기관을 사용하는 경우에는 NFC-e SP처럼 {{url}} 변수의 URL을 교체함.
  • 이벤트는 tpEvento 코드 참고용 폴더로 제공됨.
  • 이벤트 전송은 각 문서 모델의 RecepcaoEvento 서비스를 사용함.

생성 방식

  • 기준 자료는 gen_inventario.py이며, 이 파일이 inventario.json을 생성함.
  • build_collection.py가 Postman용 .json 컬렉션을 조립함.
  • 변경을 제안하려면 gen_inventario.py를 수정하고 두 스크립트를 실행한 뒤 풀 리퀘스트를 생성함.

관련 저장소

  • ciot-integradoras-postman: ANTT의 CIOT 서비스인 pefServices와 화물 운임 결제 통합 사업자 관련 저장소임.
  • antt-webservices-postman: ANTT 웹서비스인 CIOT, RNTRC, 공개 데이터 관련 저장소임.

소개

  • Stoix가 유지 관리함.
  • 라이선스는 MIT임.